Geonames

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context: default free model, optional Anthropic with BYO key, and return structure (per-model score/confidence/signals/raw_response + combined view). No contradictions.

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

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

Three sentences with zero waste. Front-loaded with main action and key details. Every sentence adds value: purpose, model behavior, use cases.

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

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

Despite no output schema, description outlines return fields. For a tool with 4 parameters (1 required), it covers purpose, parameter behavior, use cases, and model selection. No obvious 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%, so baseline is 3. Description adds beyond schema: explains default model, that '_apiKey' is only needed for Anthropic, and gives concrete examples for 'entity' (e.g., 'Pipeworx', 'OpenInvoice') and 'context' (e.g., 'Boston restaurant').

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 states specific verb 'probe' and resource 'LLMs for visibility score (0-100)'. Clearly distinguishes from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on multi-model audit rather than general Q&A.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but doesn't explicitly exclude alternatives. Could mention when not to use (e.g., when only a single simple answer is needed, prefer 'ask_pipeworx'), 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing that the tool routes to 5,724 tools across 1,497 sources, fills arguments, returns structured answers with stable citations, and works on every tier in one fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but densely informative, with critical guidance front-loaded ('PREFER OVER WEB SEARCH') followed by supported use cases, examples, and escalation paths. Each section earns its place, though it could be tightened without losing value.

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

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

There is no output schema, but the description explains the return type at a high level: structured answer with stable pipeworx:// citation URIs. It also covers breadth of domains, triggering phrases, alternative tools, and tier availability, which is sufficient for an agent to decide whether to invoke this tool.

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

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

Schema coverage is 100%; the schema already defines 'question' as a natural-language request and lists its aliases. The description adds example queries and domain coverage, but the core parameter semantics are already fully captured in the schema, so the baseline of 3 applies.

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

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

The description clearly identifies ask_pipeworx as the default tool for factual and real-world data questions, routing to verified sources and returning structured answers with citation URIs. It enumerates specific domains (SEC, FDA, FRED/BLS, USPTO, etc.) and contrasts itself with siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly states when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also provides triggering phrases and concrete examples, making the decision boundary unambiguous.

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, and the description adds genuinely useful behavioral context: it is a full working router, currently identical to ask_pipeworx, may switch behavior live when a candidate is under test, and 'falls back to nothing'. This goes beyond the annotation fields.

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 key facts are front-loaded: beta, identical router, when to use, and experimental status. The details about candidate retirement and outcome evidence are relevant context but make the description slightly longer than strictly necessary; the sentences still earn their place.

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

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

For a single-question router with rich annotations and full schema coverage, the description covers experimental status, equivalence to ask_pipeworx, and response-shape stability. It does not explain what types of questions Pipeworx generally handles, but that gap is acceptable for a universal router.

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 documented as an alias for question, and the description only adds 'same arguments' without elaborating on the question parameter's semantics. The schema already carries the semantic burden, so baseline 3 is appropriate.

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

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

The description identifies the tool as 'Beta version of ask_pipeworx' and calls it a 'universal router', making it clear this is a natural-language routing tool rather than a task-specific tool. It separates it from ask_pipeworx by labeling it the experimental edge, though it does not contrast it with ask_pipeworx_grounded or other siblings.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains this is where candidate routing improvements are tested. The when-not-to-use guidance is only implicit: an agent might infer the stable ask_pipeworx is the safer choice when experimental routing is not desired, but that exclusion is not stated directly.

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

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

Discloses refusal behavior with exact refusal_reason values, return shape on success, and the extra LLM call cost. Annotations already mark it read-only/idempotent, and the description adds substantial non-obvious behavior without contradicting them.

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

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

Dense but well-structured: purpose first, then behavior, then usage guidance and cost tradeoff. Every sentence contributes actionable information; no filler.

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

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

Describes the full success output shape and all possible refusal reasons, which is crucial given there is no output schema. Combined with annotations and sibling context, an agent has everything needed to invoke and 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?

Schema coverage is 100%, with all aliases (q, text, input, query, prompt, question) documented directly in the input schema. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

States a specific, differentiated purpose: a hallucination-resistant answer mode with same routing as ask_pipeworx but that extracts answers only from tool results. Explicitly distinguishes itself from the casual sibling 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?

Gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on'), identifies when not to use it ('prefer ask_pipeworx for casual lookups'), and discloses the cost tradeoff of one extra LLM call.

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

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

The description extensively discloses behavioral traits beyond annotations, including resolution confidence handling, short-circuit on low-confidence matches, closed market detection, wide-spread illiquidity warnings, cancellation rule parsing, and news fallback behavior. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds rich context without contradiction.

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

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

The description is very comprehensive but lengthy, with detailed sections on classifiers, fan-out examples, response shapes, resolver contract, safety, and resolution rules. While well-structured, it could be more concise for an agent-facing description; some details could be moved to external documentation. Still, every sentence serves a purpose.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous behavioral aspects), the description covers all necessary information: input formats, resolution process, fan-out logic, response structure (market, analysis, evidence), safety mechanisms, and cancellation rules. It compensates for the lack of output schema by detailing the return shape comprehensively.

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 three parameters documented. The description adds value by explaining how depth affects fan-out ('quick = 2-3 evidence sources, thorough = full fan-out') and the trade-off for include_raw (response size vs. detail). This goes beyond the schema, earning a 4.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the exact verb (research), resource (Polymarket bet with Pipeworx data), and scope (one call). The tool is well-distinguished from siblings like polymarket_arbitrage and polymarket_edges, which focus on different aspects.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly mention when to avoid this tool or what alternatives to use, relying on context from sibling tool names. This is clear but could be more direct.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA, clinical trials), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 efficient and front-loaded with key trigger phrases. Bold and structure are well used. Slight redundancy ('side-by-side comparison', 'parallel call') but overall it is appropriately sized and focused.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description provides complete context: data sources, sorting, citation URIs, and even notes on fiscal year handling. An agent can fully understand what to expect and how to interpret results.

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

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

Schema coverage is 100%, but the description adds value by explaining the meaning of each enum (company: financials, drug: adverse events) and giving format examples for values (tickers/CIKs for company, names for drug). This goes beyond the schema's minimal descriptions.

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

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

Description explicitly states the tool does side-by-side comparison of 2-5 companies or drugs, with trigger phrases like 'compare X and Y', 'X vs Y', etc. It clearly distinguishes from siblings like entity_profile (single entity lookups) and positions itself as a replacement for multiple sequential lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear usage context. It also breaks down what data is pulled for each type. Lacks explicit 'when not to use' scenarios (e.g., detailed single-entity profiling), but the context is strong.

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

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

The description adds substantial context beyond the readOnly/openWorld/idempotent annotations: account/paid-tier requirements, parallel facet decomposition, gap[] semantics with 'never invented', contradiction[] flags, stable citation URIs, semantic excerpting, and expected latency ranges. No contradictions with the annotations; the 'not open-web search' clarification refines the openWorldHint rather than contradicting it.

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 almost every sentence earns its place by covering usage conditions, output structure, citations, and caveats. It is reasonably front-loaded with the account requirement and the key differentiator ('NOT open-web search'). Some redundancy exists in the repeated ask_pipeworx comparisons, but the density warrants a 4 rather than a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values — it delivers with details on the findings packet, gaps[], contradictions[], hop field, citation_uri resolvability, and excerpting behavior. It also covers edge cases like breaking news returning mostly empty gaps, along with timing expectations, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by explaining the depth tiers' behavior beyond the enum labels: quick=3 facets single hop, standard=gap recovery + contradictions, thorough=chases leads and costs more. It also reassures that broad questions are acceptable, exceeding the schema's minimal note.

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 precise verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself from both open-web search and sibling tools. It also provides example questions that clarify the intended domain (regulatory/financial exposure, filings + market picture).

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?

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'), and a specific alternative for breaking/colloquial current-news topics. It also specifies account requirements and the fallback for unsigned-in users, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds key behavior: returns top-N relevant tools with full schemas and examples, ready to call directly. 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?

Somewhat long but every sentence adds value. Front-loads core purpose and usage. Could be slightly tighter, but well-structured.

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

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

Given no output schema, the description fully explains what is returned (names, descriptions, schemas with examples) and that results are ready to call. No gaps for this 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 coverage is 100%, so baseline is 3. Description adds aliases explanation and default/max for limit, but that is also in schema. No significant new semantic info beyond what schema provides.

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

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

The description clearly states it finds tools by describing the data or task, lists numerous specific domains, and distinguishes itself from siblings as the discovery tool. The verb 'Find' and resource 'tools' are specific.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available'. Lacks explicit when-not-to-use or 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the fan-out across multiple sources, specifics of returned data (e.g., up to 5 filings, latest fundamentals), fallback behavior (GDELT→GNews), and a sunset note for patents. This adds significant behavioral context.

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

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

The description is front-loaded with example queries and a clear statement of purpose. It is dense but slightly longer than necessary; however, every sentence serves a purpose. It is well-structured and easy to parse.

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 data sources, fallbacks, limitations), the description covers all key aspects: input types, output fields, data sourcing, caveats (patents sunset, news fallback), and output structure. No output schema exists, but description sufficiently explains return values.

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 clear descriptions for both parameters. The description reiterates the input constraints (ticker/CIK, no names) but does not add new semantic detail 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 clearly states the tool's purpose: a full cross-source profile of a US public company in one parallel call. It provides example user queries and explicitly distinguishes it from chaining single-purpose lookups, aligning with sibling differentiation.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups when a holistic view is needed. It also provides specific guidance on supported inputs (ticker or CIK) and directs users to resolve_entity for names, covering when to use and when not to.

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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by listing the return fields (place name, country, admin region, postal code, coordinates) and explaining the two query modes, surpassing the annotation baseline.

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

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

Two crisp sentences: first states purpose, second elaborates with examples and return fields. No wasted words, front-loaded, and easy to parse.

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 5 parameters (1 required) and no output schema, the description covers both usage modes, return fields, and the importance of country. It is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining the two mutually exclusive usage modes (postal_code or place), which helps the agent choose parameters correctly.

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

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

The description clearly states the tool's purpose: looking up postal/ZIP codes and places by each other, with concrete examples. It distinguishes itself from siblings like search_geonames by focusing on reverse lookups.

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

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

The description provides clear usage instructions: use 'postal_code' with country to find places, or 'place' with country to find codes. It emphasizes the importance of country but does not explicitly mention alternatives or when not to use the tool.

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

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

Annotations already indicate destructive and idempotent behavior. Description confirms deletion but does not explicitly state idempotency or provide additional behavioral context beyond what annotations provide.

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

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

Two sentences containing only essential information, front-loaded with purpose.

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

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

Adequate for a simple tool with one parameter and no output schema. Missing explicit mention of idempotent behavior (deleting a non-existent key is safe) despite annotation.

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 property description 'Memory key to delete' is clear. Description adds no extra parameter meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly says when to use: context stale, task done, or clearing sensitive data. Also mentions pairing with sibling tools.

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

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

Annotations already indicate safe, idempotent read. Description adds how it works (fetches page, extracts title/description/key links, outputs markdown) and output location hint. 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?

Four sentences: purpose, process, output, use cases. Nothing redundant, front-loaded with key action.

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

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

Simple tool with two parameters, no output schema. Description covers what it does, output format, and use cases. Minor missing details (e.g., error handling) are acceptable for this 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 coverage is 100%, so description adds no new parameter info. 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 'generate' and resource 'llms.txt file', clearly stating it produces a standard markdown file for AI crawlers. It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing). Does not mention when to avoid using or compare with siblings, but context is clear and 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 the tool as read-only, idempotent, and non-destructive. The description adds that results are sorted by distance, which is behavioral context beyond what annotations provide. 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 extremely concise with two sentences and an example that front-loads the action. Every sentence adds value without unnecessary detail.

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

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

Given the tool's low complexity, full schema coverage, presence of annotations, and existence of an output schema, the description provides sufficient context. It explains the tool's function, return type, and ordering, leaving no gap for the agent to misinterpret.

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, so the baseline is 3. The description's example shows usage but does not add semantic meaning beyond what the schema already provides for each 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 finds places near a given latitude/longitude, specifying return types (cities, landmarks, features) and ordering (by distance). The example with Paris coordinates concretely illustrates the purpose. This is specific and 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?

No explicit guidance on when to use this tool versus alternative sibling tools like search_geonames or search_within. The description implies usage through the example but does not provide context for when not to use it or mention any prerequisites.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by listing the exact return fields (timezone ID, offsets, local time, sunrise, sunset) and an example, providing richer behavioral context beyond the structured annotations.

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

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

The description is two sentences: the first states purpose and returns, the second provides an example. No wasted words, front-loaded with key information.

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

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

Given the tool's simplicity (3 parameters, no nested objects), the description fully covers what the tool does, what it returns, and how to use it via example. Annotations and output schema (implied) further support completeness.

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

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

Schema description coverage is 100% with each parameter having a description. The description adds an example call but does not significantly enhance parameter meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

Description clearly states 'Get timezone information for a latitude/longitude location,' which is specific and distinct from sibling tools like search_geonames. It provides a precise verb-resource combination.

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

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

The description explicitly states when to use this tool (for timezone info given lat/lng). It does not provide explicit when-not-to-use or alternative tools, but the context is clear enough to avoid misuse.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds return field details but no additional behavioral traits 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, front-loaded with purpose and return fields, then usage guidance. 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 list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. Complete given the low 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 covers the single parameter with a description (100% coverage). The tool description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states it lists the caller's active subscriptions and specifies return fields. However, it does not explicitly differentiate from sibling tools like 'subscribe' or 'unsubscribe', though the purpose is clear.

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

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

Provides explicit usage guidance: use to review subscriptions before adding more or to get an id for cancellation. This helps the agent decide when to invoke.

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

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

The description discloses follow-up behavior (claim_token for checking resolution status), rate limits (5 per identifier per day), roadmap impact, and the fact that it's free. These details go well beyond the sparse annotations (all false hints) and there is no contradiction.

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

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

The description is concise despite its length: each sentence carries unique information, structured logically from purpose to usage to exclusions to follow-up. It front-loads the core purpose and avoids 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 4 parameters, nested objects, no output schema, and sparse annotations, the description is remarkably complete. It covers purpose, usage boundaries, parameter behavior, token lifecycle, and operational constraints, leaving no meaningful questions unanswered.

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 has 100% parameter descriptions, the tool description enriches semantics: it explains how claim_token is used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), instructs users to describe issues in terms of Pipeworx tools, and clarifies the context object's purpose—adding value beyond the raw 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 opens with a specific action—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and clearly enumerates the feedback types (bug, feature/data_gap, praise). It names the resource (Pipeworx tools) and differentiates from sibling research tools by being the only feedback channel.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes an exclusion criterion—'ONLY for tools served by this Pipeworx connection'—and directs users to file with the correct server otherwise.

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

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

Description adds value beyond annotations: explains data source (CF analytics-engine), no PII, caching behavior (5min-1h). Annotations already declare readOnly, idempotent, non-destructive.

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 with bulleted use cases, no filler. Front-loaded with return type and window options.

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 one optional parameter, no output schema, and strong annotations, the description covers return structure, data source, privacy, and caching adequately.

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

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

Schema coverage is 100% with a well-described enum parameter. Description adds practical guidance: shorter windows for hot trends, longer for steady-state demand.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a specified window. Distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on trending data rather than answering questions.

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

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

Provides three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case). Does not include explicit when-not-to-use, but context is clear enough.

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

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

Description discloses extensive behavioral details beyond annotations, including algorithms (monotonicity, partition-sum), semantic anchor threshold (Jaccard ≥0.30), partition filter (placeholder slugs >20% nullify), and fill check logic. Aligns with readOnlyHint and non-destructive 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?

While dense, every sentence serves a purpose and the description is front-loaded with the primary action. Some redundancy could be trimmed, but the complexity justifies the length. Structured logically from overview to modes to details.

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

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

For a complex arbitrage tool with no output schema, the description thoroughly explains response fields, fill check mechanics, and limitations. References sibling tools for complementary functionality. Covers all necessary guidance for correct invocation and interpretation.

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

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

Schema coverage is 100% with good descriptions, and the description adds significant value by explaining behavior, giving concrete examples, and detailing algorithm implications. Slightly above baseline due to rich extra context.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two distinct modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to call with no args (trending scan), pass `event` for specific market, or `topic` for cross-event scanning. Provides recommendations, examples, and conditions to avoid (e.g., fill check warning not to trade if realizable_edge_pp ≤ 0). References sibling tool 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 extensively discloses behavioral traits beyond annotations: it details model families (crypto_price, news_momentum, structural_arbitrage), edge calculation (edge_pp_net after slippage), Kelly sizing caps (0.25), 24h move warning, caching at KV level keyed on all knobs, and diagnostics for empty segments. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all true/false appropriately).

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 compact with information. It front-loads the purpose and then systematically covers segments, edge fields, knobs, and response structure. Every sentence adds value, though the wall of text could be better organized with bullet points or sections for improved scanning by an AI agent.

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

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

Given 9 parameters, no output schema, and rich annotations, the description is remarkably complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), caching behavior (1h at KV level), and even provides context on limitations (Fed bets unreliable without paid data). No obvious gaps for an agent to invoke the tool confidently.

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

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

Schema coverage is 100% (baseline 3). The description adds significant meaning beyond schema: it explains the purpose of each knob (e.g., 'min_liquidity' description explains dropping thin-book opportunities), provides examples (e.g., 'Set to 2 to require tight books'), and clarifies interactions (e.g., 'min_partition_leg_kelly' applies to per-leg Kelly inside partitions). This adds substantial value beyond parameter names and 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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses a specific verb (scan) and resource (Polymarket markets), and distinguishes itself from siblings like polymarket_arbitrage by focusing on disagreement with Pipeworx data rather than pure arbitrage or 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 provides explicit context for when to use the tool ('what should I bet on today') and explains the various filters and knobs. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage, though the detailed breakdown of segments and model families implies distinctions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds substantial behavioral context: it reads from daily snapshots with a 60-day TTL, decay numbers from daily closes, snapshot gaps on cache misses, and explains the response structure including tracked, expired, and snapshot_dates arrays with their fields. 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 detailed and well-organized, starting with the purpose then explaining the response structure with labeled arrays. However, it is somewhat verbose and includes information that could be more terse, such as the full breakdown of tracked arrays and their sub-fields. Still, it remains clear.

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 (time-series decay analysis) and no output schema, the description fully explains the return format: tracked, expired, snapshot_dates arrays with their fields, and limitations (TTL, gaps). This provides sufficient context 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% with descriptions for both parameters (days, window). The description adds meaning beyond schema: explains defaults (14 for days, '1wk' for window), constraints (max 30 for days), and the concept of snapshot families ('window family'). This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers 'how long has this edge existed and is it shrinking?'' It uses specific verbs and resources, and distinguishes from siblings like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description provides clear context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It also gives default and max values for the days parameter. However, it does not explicitly mention when not to use or list alternatives, though sibling tools are available.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint (all safe). The description adds rich behavioral context: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), warns about thin books and forced directional risk. This goes beyond annotations to explain exactly what the tool does internally and what risks it mitigates.

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 long but well-structured: starts with purpose, then uses clear section headers for SINGLE-MARKET and BASKET modes. Every sentence adds value (no filler). However, it could be slightly more concise without losing clarity, hence a 4 instead of 5.

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

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

Despite lacking an output schema, the description fully documents all return values for both modes (top_of_book, verdict for single-market; theoretical_sum, capture_ratio, thin_legs for basket). It explains edge cases (thin books, partial fills) and the dominant loss mode. Combined with high schema coverage and annotations, the description is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond schema field descriptions. For example, it explains that `size_usd` for basket is 'settlement notional — shares per leg, each paying $1 at resolution,' and describes default behavior for `side` in basket mode (auto-detect based on partition sum). Each parameter's role in both modes is clearly elaborated.

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

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

Description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes with precise verb-resource combinations. Additionally, it explicitly ties usage to sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' making its purpose unambiguous and distinct.

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

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

The description provides explicit when-to-use guidance: before acting on arbitrage signals or edge trades above ~$500. It also explains when-not-to-use by warning about partial basket fills converting arb into unhedged directional positions. Requirements are clear (one of `market` or `event`), and the two modes are thoroughly explained with usage context.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes much further: fees are 'gross, not a net tradeable edge,' unclassified legs are 'NEVER paired,' and null temporal_alignment 'means it could not be computed, not that the two sides align.' It also discloses that compatibility warnings can be non-empty even when matched_pairs>0, giving the agent accurate expectations 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 dense but well-structured with labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the core purpose. However, temporal_alignment_unknown is explained twice (in the codes list and again in the temporal_alignment field), and 'pre-mapped ≠ tradeable' echoes an earlier warning, so a little pruning would tighten it.

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

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

There is no output schema, so the description must explain return values, and it does—leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning/codes[], flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment, fees_note, and skipped counters. It is complete for a complex cross-venue spread tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds mode semantics—'topic' auto-fetches the matching event, while explicit params 'Overrides the topic-mapped side'—and confirms both modes 'run the identical token-overlap matcher.' This is valuable context not present in 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 opening sentence defines a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools by focusing on the cross-venue delta rather than single-venue edges or research 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?

The description explains two invocation modes (topic shortcuts vs. explicit ticker/slug) and provides a critical caution: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' However, it does not explicitly name sibling alternatives or state when to choose this over polymarket_arbitrage, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to reiterate safety. It adds value by disclosing scoping ('Scoped to your identifier') and pairing with remember/forget. It does not describe return format or performance, but given the simplicity and annotation coverage, this is sufficient.

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

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

Three sentences, each with clear purpose. First sentence states the core action. Second explains when to use. Third adds important context about scoping and pairing. No redundant or vague language. Perfectly front-loaded.

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

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

With no output schema, the description should explain what the tool returns (e.g., value format, list of keys). It only says 'retrieve a value' and 'list all saved keys' but does not specify the data structure or type. However, given the tool's simplicity and symmetry with remember, this is a mild omission. It is adequate but not fully complete.

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

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

Schema description coverage is 100% and the schema already explains the key parameter and omission behavior. The tool description reinforces this with additional context about listing all keys and the use case. It adds marginal value but is consistent and clear.

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

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

Description clearly states verb 'Retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. It distinguishes from siblings by naming remember and forget, and explains when to use each mode (omit key for listing). The use case is concrete: look up stored context like ticker or address.

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

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

Description explicitly states to use this tool to retrieve previously stored context without re-deriving. It implies when not to use (when you want to save, use remember; to delete, use forget). However, it could be more explicit about situations where recall is inappropriate (e.g., stale data). Nonetheless, the guidance is clear and actionable.

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

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

Adds significant context beyond annotations: explains mark_read side effects (flags events as read), return data structure, and polling suitability. No contradictions with readOnlyHint, idempotentHint, etc.

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

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

Single paragraph, front-loaded with purpose, every sentence contributes. Efficient and well-structured with 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?

Covers purpose, return contents, filtering, side effects, polling, and an alternative method. Without an output schema, it adequately describes what is returned. Annotations cover safety, so 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 5 parameters, baseline 3. Description adds value with an example filter type (sec_8k) and clarifies mark_read behavior, improving usability beyond schema alone.

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

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

Description clearly states the tool pulls fired events from a subscription feed, lists what each alert carries, and mentions filtering. It distinguishes itself from sibling tools like list_subscriptions by focusing on events rather than 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?

Describes when to use (pull alerts, poll) and provides an alternative endpoint for scripts/dashboards. However, it does not explicitly compare to other sibling tools or state when not to 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 indicate read-only, idempotent, non-destructive behavior. The description adds details on source fan-out, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (changes[], total_changes, citation URIs). 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 a single, dense paragraph that front-loads example queries, then explains function, sources, parameter hints, return format, and sibling differentiation. Every sentence is necessary and adds 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?

Given the tool's complexity (multiple sources, fallback, soft-fail, structured return), the description covers all aspects: purpose, sources, parameters, return format, and alternative tool. No output schema exists, but return structure is described. Idempotent, read-only behavior is clear from annotations.

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

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

Schema coverage is 100%, so parameters are already described. The tool description adds extra value by providing recommended usage for 'since' (e.g., 'Use 30d or 1m for typical monitoring') and examples for 'value' (ticker or CIK). Only minor improvement possible.

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 provides a change feed for a company by aggregating multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives concrete example queries and explicitly distinguishes from the sibling tool entity_profile, which provides static profiles.

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

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

It provides explicit usage examples (e.g., 'What's new with X', 'latest on Y') and directly contrasts with entity_profile, stating when to use that alternative. This gives clear guidance on when to select 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?

Discloses beyond annotations: key-value scoped by identifier, persistent for auth users, 24-hour for anonymous. Annotations provide idempotentHint and destructiveHint, description adds 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?

Four concise sentences. Front-loaded with purpose. No redundancy or fluff.

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

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

For a simple tool with two string params and no output schema, description covers all essential: usage context, pairing, scoping, persistence. No gaps.

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

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

Schema has 100% coverage with descriptions for key and value. Description adds examples but doesn't introduce new semantic constraints 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 verb 'Save data' and resource 'key-value pair'. Specifies scope: across conversation or sessions. Examples (ticker, address, preference) distinguish 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?

Explicitly says when to use: when discovering something worth carrying forward. Lists pairs with recall and forget, and mentions scoping by identifier and persistence duration.

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 establish read-only, idempotent, non-destructive behavior, so the description is free to add deep behavioral context. It discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` fields, and the `figi_candidates` fallback for ambiguity — all beyond what annotations provide.

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

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

The description is long and dense, but it is well-structured with clear sections (examples, supported types, graceful degradation) and every sentence contributes operational detail. It is front-loaded with purpose and usage, yet the sheer volume of parenthetical qualification makes it heavier than strictly necessary.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: company resolutions list CIK/ticker/name/LEI/FIGI with source labels and `unresolved` handling; drug resolutions state RxCUI/ingredient/brand and citation. Edge cases (ambiguous bonds, ISIN mapping, unavailable enrichment) are all covered.

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

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

Schema coverage is 100%, but the description adds substantial meaning: `type` gets per-enum behavior details (company vs drug), and `value` gets examples, input-form alternatives (ticker, CIK, ISIN, name), and a concrete caution about trailing security-class words. This goes well beyond the schema's terse property descriptions.

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

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

The description opens with concrete user-phrase examples and a crisp mission: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names specific resources (CIK, ticker, LEI, FIGI, RxCUI) and supported types, making the tool's function unmistakable and differentiating it as a prerequisite that 'other tools require as input.'

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 present: 'Use FIRST whenever you have a name but need an ID.' It also gives input-format instructions (e.g., pass the issuer exactly as printed, not the full noun phrase) and explains ambiguous-name behavior. However, it never names alternative tools or states when not to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds details: it probes each entity, returns ranked list with score, confidence, signal density. No contradiction; adds 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?

Description is two sentences plus a short third; each sentence serves a purpose (main function, process, utility). Front-loaded with the core action. No extraneous 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?

Missing output schema is compensated by description stating return fields. Parameters are fully described. Could mention potential limitations like rate limiting, but overall complete for the task.

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 value by noting first entity is treated as subject and context disambiguates common names, which goes beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check by specifying it is a batch comparison, and uses of ai_visibility_check internally.

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

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

Provides explicit use case ('competitive AI-marketing audits') and an example question. Implicitly contrasts with ai_visibility_check for single entities, but does not fully enumerate when not to use or compare with other siblings like compare_entities.

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

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

Adds behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts while rest still returns. Annotations already indicate read-only, idempotent, non-destructive, so description adds specific failure details.

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 dense paragraph with core purpose front-loaded and details following. Every sentence adds value, though the structure could be slightly more organized with bullet points. Still efficient and focused.

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

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

Covers inputs, outputs, edge cases (partial failures, timeouts), ecosystem scope, and alternatives. Since no output schema exists, description compensates by detailing return format (summary block, advisories, links, versions). Complete for a composite tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds that scoped packages like '@types/node' are accepted for the 'package' parameter, but otherwise no significant enhancement beyond the schema's definitions. Meets but does not exceed 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?

Description specifies a composite check for npm packages including license, advisories, version history, bundle size, and more. It clearly states the verb 'check' and resource 'npm package', and distinguishes from siblings by noting NPM-only scope and alternative tools for other ecosystems.

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

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

Explicitly states when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also clarifies NPM-only in v1 and directs other ecosystems to deps.dev:version, providing clear when-not-to-use guidance.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds context about the admin_region field and worldwide coverage. It does not contradict annotations and provides useful behavioral details.

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

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

The description is front-loaded with the primary purpose, includes clear examples, and ends with a sibling reference. Every sentence adds value, and the structure is logical.

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 (search with multiple parameters and output schema), the description is comprehensive. It details the admin_region field, gives examples for various countries, and mentions output fields. It also references a sibling tool for nearby searches.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds examples and explains the admin_region field's meaning, providing additional context beyond the schema.

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

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

The description explicitly states it searches for places by name and returns administrative divisions, country, coordinates, population, and feature type. It provides specific examples and distinguishes from the sibling tool get_nearby.

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 with examples for different countries and explicitly mentions when to use get_nearby as an alternative. It gives concrete instructions on how to use the tool.

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

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

Adds specific technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already indicate idempotent and non-destructive, and description aligns without contradiction.

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

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

Description is focused and front-loaded with core functionality. Every sentence adds information, though it could be slightly more terse 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, description fully explains return values (passages with offsets and scores). Includes pairing advice with ask_pipeworx_grounded and truncation behavior, making it self-sufficient 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 covers all 3 parameters (100% coverage). Description adds value by explaining the nature of 'query' with natural-language examples and indicating 'limit' controls top-N passages, plus the result format (offsets, scores). Slightly above baseline due to useful examples.

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 'Semantic search INSIDE a fetched record' with examples (SEC 10-K, article). Distinguishes from siblings by specifying it operates on provided text, but does not explicitly contrast with similar tools like search_geonames.

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

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

Explicitly advises using when the record is too large to include directly, saving context. Mentions pairing with ask_pipeworx_grounded for grounding over passages, but does not explicitly list conditions when not to 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 indicate idempotent and non-destructive. Description adds key behaviors: account requirement, type-specific filtering, SMS cap, webhook signing secret one-time return, and auto-disable after 10 failures. 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?

Tightly packed with information, front-loaded with main action and requirements. Slightly long but every sentence adds value; minor structural improvement possible.

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

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

Covers purpose, parameters, behavior, constraints, and delivery channels. No output schema but returns subscription id as stated. Could mention failure handling or quota details.

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?

100% schema coverage augmented by detailed examples and usage constraints. Adds rich meaning to each parameter (e.g., enum items, nested object structures) beyond schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription, lists supported event stream types with examples, and distinguishes from siblings like 'unsubscribe' 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?

Provides explicit context: requires Pipeworx OAuth account, mentions feed vs email/SMS/webhook delivery, and suggests pulling via 'recent_alerts' as alternative. Lacks explicit when-not-to-use vs all 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, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it returns 'category-bucketed example questions' and uses the 'live catalog', which are useful behavioral details 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 detailed but well-structured: it starts with common questions, then explains behavior, and ends with a usage recommendation. While slightly long, it avoids redundancy and is front-loaded with purpose.

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

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

Given no output schema, the description adequately explains the return format (categories, example questions, tool shapes) and the parameter behavior. It also provides context about usage order relative to sibling tools, making it fully informative for an agent.

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

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

The schema describes the optional 'topic' parameter with a list of values (e.g., finance, pharma). The description adds context that omitting returns a full spread and that the values focus the results, which 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 this is the onboarding entry point for new agents, answering queries like 'What can I ask?' and explicitly distinguishes it from sibling tools by explaining its role as a discovery 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 recommends using this tool 'FIRST when you do not yet know what Pipeworx can do' and mentions learning to call meta-tools, but could more explicitly state when not to use it (e.g., if you already know what to ask).

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 details beyond annotations: it states the row is deactivated (not deleted) and historical events remain available. This aligns with destructiveHint=false and idempotentHint=true, and adds ownership enforcement (not 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 concise: two sentences efficiently convey the action, ownership constraint, and deactivation behavior. No unnecessary words.

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

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

Given the simple tool (one parameter, no output schema), the description covers the action, constraint, and effect adequately. It fully explains what the tool does and its 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?

The description mentions the id parameter but adds limited semantics beyond the schema. With 100% schema coverage, the baseline is 3. No additional details on format or origin are provided.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource (subscription). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description provides clear context for when to use the tool: to cancel a subscription by id. It also includes ownership enforcement ('you can only cancel your own subscriptions'), which implicitly guides against using for others' subscriptions. No explicit alternatives are mentioned, but the sibling list provides context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable context beyond annotations: the meaning of 'could_not_verify' (the check did not happen, and it is not evidence), the distinction from 'unsupported', and the two pipeline routes. 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 fairly long but each sentence earns its place. It front-loads the purpose with natural-language triggers, then explains the pipeline split, verdicts, and an important caller warning. It is structured logically, though slightly verbose, so a 4 is appropriate.

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 two-parameter tool with no output schema, the description is remarkably complete: it describes the return payload (verdict, actual value, citation, reasoning), explains the two distinct execution paths, and details the critical semantics of 'could_not_verify' vs 'unsupported'. This fully equips an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter semantics beyond the schema; it references tolerance_pct in the context of hallucination detection, but the schema already explains the override and default behavior. The claim parameter is also fully described 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 clearly states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It includes example natural-language triggers and distinguishes between the structured SEC EDGAR fast path and the general grounded pipeline, which helps differentiate it from the sibling ask_pipeworx_grounded 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?

Explicit when-to-use guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when the structured path vs grounded pipeline applies based on claim type. However, it does not explicitly name alternative tools to use instead, so it stops short of a 5.

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