What3words

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: per-model scoring details (score, confidence, signals, raw_response), the default free model, and that Anthropic usage requires a Bring-Your-Own-Key with direct payment. This goes beyond annotations.

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

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

The description is two sentences, front-loaded with the main action and output format. Every sentence provides essential information without redundancy. It is efficiently structured for quick parsing.

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 4 parameters with 100% schema coverage and no output schema, the description compensates by explaining the return structure (per-model and combined view). It also covers use cases and model options, making it complete for an AI agent to understand and invoke 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 description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the default model, the condition for using _apiKey, and how the context parameter helps disambiguate entities. This exceeds the baseline.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs for visibility'), clearly stating it scores visibility (0-100) per model. It distinguishes itself from sibling tools by focusing on AI visibility scoring, with explicit use cases like AI-marketing audits and brand checks.

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 mentions when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides context about default vs. paid models. It does not explicitly state when not to use it or name alternative sibling tools, but the guidance is clear enough for appropriate 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, openWorldHint, idempotentHint, and non-destructive behavior, lowering the burden. The description adds genuine context beyond those: the tool is a meta-router that internally selects among thousands of sub-tools, infers/fills arguments, and returns stable citation URIs. It also pre-empts the news-routing question by noting ask_pipeworx already covers live news feeds. No contradictions with annotations.

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

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

Long but appropriately so for a central meta-tool with 34 siblings. The most critical instruction ('PREFER OVER WEB SEARCH') is front-loaded, domains and triggers are dense lists rather than prose, and every sentence earns its place — the alternatives guidance and examples are essential disambiguation rather than filler. Slightly longer than strictly necessary, but justified by its router role.

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 meta-router with no output schema, the description covers the essentials: supported domains, trigger phrasing, example queries, return format (structured answer with stable pipeworx:// URIs), and sibling routing. It does not describe failure behavior when no source matches or timeouts on fan-out, but those are minor gaps against a description that already handles the main invocation decision fully.

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 schema documents 'question' and its five aliases clearly. The description adds value beyond that by teaching query formulation: the six concrete examples ('current US unemployment rate', 'Apple's latest 10-K', 'adverse events for ozempic') demonstrate expected breadths, formats, and entity types, which helps an agent craft a well-scoped question.

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

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

The description states a specific verb and resource: it routes questions to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It explicitly differentiates itself from web search and names sibling alternatives (ask_pipeworx_grounded, deep_research), so an agent can tell them apart immediately.

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?

Extremely explicit: it opens with 'PREFER OVER WEB SEARCH', lists concrete trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), enumerates domains, and gives six illustrative examples. It also states when NOT to use it by routing to ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions — leaving no ambiguity about alternatives.

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

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

The description adds substantial behavioral context beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It discloses that the tool is a full working router with no fallback, that candidate improvements may be live or inactive, that it currently matches ask_pipeworx exactly, and that outputs share the same response shape. No annotation contradiction exists.

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-organized, front-loading the core beta-identical-router fact before explaining current state and usage. The retired-candidate date is slightly extraneous and the phrase 'same ... same ... same' is repetitive, but each sentence contributes useful behavioral or usage context.

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 one-required-parameter proxy tool with rich annotations, the description covers all needed calling context: what it does, how it differs from the stable sibling, when to use it, current behavioral status, fallback behavior, and response-shape compatibility with ask_pipeworx. The absence of an output schema is mitigated by the explicit 'same response shape' statement.

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 documents every parameter, including aliases for 'question'. The description adds no new parameter-level semantics, though it does reference 'same arguments' as ask_pipeworx. This meets the baseline for fully schema-covered parameters without going beyond it.

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

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

The description immediately identifies the tool as a beta version of ask_pipeworx and states exactly what that means: the same universal router with the same tools, arguments, and response shape. It clearly distinguishes this experimental variant from the stable ask_pipeworx sibling by explaining the only meaningful difference is candidate routing improvements.

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

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

The description gives explicit usage direction: "Use it exactly like ask_pipeworx when you want the newest routing." It also explains that results are compared against the stable router, which clarifies its evaluation purpose. It does not explicitly state when not to use it, but the stable ask_pipeworx alternative is implied by the beta-vs-stable contrast.

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

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

The description goes far beyond the annotations by disclosing the exact success return shape, the explicit refusal reasons, and the behavioral guarantee that answers are extracted only from tool results. It also mentions the extra LLM call cost. These are valuable behavioral details not present in the readOnlyHint or idempotentHint annotations.

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

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

The description is dense but every sentence earns its place: it states the purpose, describes the mechanism, gives the return contract, lists refusal reasons, specifies when to use it, and when to avoid it. The most important differentiator is front-loaded, and the structure is easy for an agent to scan.

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 compensates by fully specifying the success and refusal response shapes, including all refusal reason values. It also covers routing, sourcing, cost, and usage boundaries, making it complete enough for an agent to invoke the tool correctly and interpret its result.

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

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

The input schema already provides 100% coverage, including a detailed description of the question parameter and its aliases. The tool description adds no new per-parameter semantics beyond implying the question is in natural language, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a hallucination-resistant, grounded answer mode for high-stakes reads, using a specific verb and resource. It explicitly distinguishes it from the sibling ask_pipeworx by describing the same routing but with extraction limited to tool results. This makes the tool's function immediately clear 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 gives explicit when-to-use guidance: when an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also names the alternative to prefer for casual lookups (ask_pipeworx) and explains the cost tradeoff, 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns ranked suggestions and can bias by location. This additional context is valuable but does not contradict 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 extremely concise: two sentences, no unnecessary words. The main action is front-loaded, and every word contributes value. Ideal structure for 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 the presence of an output schema (not shown here), the description does not need to explain return values. It covers the input and optional behavior. It lacks mention of error handling or edge cases, but for a straightforward suggestion tool, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning: 'partial / mistyped 3-word input' clarifies the input parameter, and 'optional focus point biases results toward proximity' adds context to focus_latitude/focus_longitude. This exceeds the minimal schema documentation.

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

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

The description clearly states the tool's purpose: it returns ranked suggestions for partial or mistyped 3-word input. It also mentions the optional focus point parameter for proximity bias. This distinguishes it from siblings like 'words_to_coords' (exact conversion) and 'coords_to_words'.

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

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

The description implies usage context: use when input is partial or mistyped, optionally with a focus point. It provides clear context but does not explicitly state when not to use this tool or name alternatives. Given sibling tools, the context is sufficient for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: resolution confidence levels, closed market handling, wide-spread warnings, cancellation rule parsing, and short-circuiting on low confidence. It also explains fan-out behavior and news field fallback mechanisms. No contradictions with annotations.

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

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

Description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) that aid parsing. Every sentence adds value; however, it could be slightly more concise. Given the complexity of the tool, this length is justified.

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

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

Given no output schema, the description thoroughly covers return values: response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives), parent event extraction, news fields with fallback, and safety/edge cases. It is entirely self-contained for an agent to understand what to expect.

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 with descriptions (100% coverage). Description adds value by explaining market parameter input flexibility (slug, URL, text) and hints at how depth affects fan-out. While baseline is 3 due to full schema coverage, the extra context on parameter interplay justifies a higher score.

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 researches a single Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It also lists use cases like 'should I bet on X' which makes purpose unambiguous.

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

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

Explicit usage guidance is provided ('Use for should I bet on X…') along with detailed classification types and fan-out examples. However, it does not explicitly state when not to use this tool versus siblings like polymarket_edges or ask_pipeworx, leaving some ambiguity.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent. Description adds significant behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data with citation URIs, and efficiency replacing 8-15 sequential lookups. Fully transparent 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 efficient and well-structured. Front-loaded with natural language query examples to help pattern matching, followed by clear bullet-point style details. Every sentence earns its place with 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?

Given no output schema, description fully explains return format (paired data + citation URIs), sorting, and metric details. Covers both entity types, input constraints (2-5), and data sources. Contextually complete for an agent to invoke correctly without needing additional reference.

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

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

Schema coverage is 100% but description adds crucial context: explains that type 'company' pulls 10-K financials and type 'drug' pulls FAERS/FDA/trial counts, and clarifies that values for company should be tickers/CIKs while for drug they are names. Also explains max/min constraints and sorting behavior. Adds significant value beyond schema.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single call. It provides specific query examples like 'compare X and Y' and 'which is bigger' and explicitly differentiates from sequential single-pack lookups and sibling tools like entity_profile.

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 to always prefer this tool over sequential lookups when comparing entities. Provides context on what each type returns (financials for company, adverse events for drug). Does not explicitly mention when not to use, but the preference statement is strong enough for an agent to infer correct usage.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds that the tool defaults to English and accepts a 2-letter language code, which is 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?

Two sentences, no wasted words. The most important information (purpose and default language) comes first. Every sentence earns its place.

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

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

Given the tool's simplicity and the presence of an output schema, the description is complete. It covers the core transformation, default behavior, and optional parameter usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the output format (3-word address) and the language parameter behavior (default English, 2-letter code), which complements the schema descriptions.

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

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

The description explicitly states the verb (convert), resource (lat/lon to what3words 3-word address), and distinguishes from the sibling tool 'words_to_coords' which does the reverse. It also clarifies default behavior and language option.

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

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

The description implies usage context—converting coordinates to words—and the sibling list includes the inverse tool, providing indirect guidance. However, it does not explicitly state when not to use it or suggest alternatives for non-what3words cases.

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=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds substantial behavioral context beyond those hints: parallel tool routing, gap handling (gaps[] never invented), contradictions[] behavior, semantic excerpting rather than head-truncation, hop field semantics, citation fetchability guarantees, and expected latency ranges (15-60s, up to ~90s). This goes well beyond what annotations alone provide.

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

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

The description is long but information-dense: every clause adds operational value (account requirements, alternatives, decomposition behavior, gap semantics, hop field, citation URI guarantee, excerpting, latency). It is front-loaded with the critical account/sign-in warning and scoping statement. It could be tightened slightly, but the length is justified by the tool's behavioral complexity.

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

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

For a research tool with no output schema, the description thoroughly covers what an agent needs: what it returns (findings packet with evidence/confidence/source/fetched_at/citation), what it doesn't do (invent answers, gaps[] for unanswered facets), when to pick alternatives (single lookup, news topics), depth tiers and cost implications, latency expectations, and citation resolvability. The tool's complexity is high, and the description is proportionate.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds context around depth tiers (explains quick/standard/thorough behavior, paid plan requirement for thorough) which the enum alone doesn't convey. This matches the baseline 3 for high schema coverage; the depth behavior detail is a slight bonus but the description doesn't dramatically extend param semantics beyond what the schema states.

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: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly contrasts with open-web search and names specific use cases (broad/multi-part questions over structured data) with examples. The verb-object pair (research across structured sources) is specific and distinguishable from siblings like 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?

The description gives explicit when-to-use guidance: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, use ask_pipeworx for news/current topics that aren't in the structured catalog. It also specifies account requirements and alternatives when not signed in. Multiple exclusions and alternatives are named clearly.

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=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return format (top-N tools with full schemas and curated examples) and stating results are ready to call directly, which is not captured 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 compact yet comprehensive: it states purpose, lists use scenarios, details return value, and provides usage guidance—all in a few well-structured sentences. Every sentence adds value, and key information is front-loaded.

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

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

The description fully covers what the tool returns (top-N tools with names, descriptions, full input schemas, examples, and readiness to call) and when to use it. Given no output schema, this provides all necessary context. The tool is simple (one required param), making this 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?

The description explains that the query parameter is a 'natural language description' and provides concrete examples (e.g., 'analyze housing market trends'). It notes multiple aliases (task, q, search, description) and the limit parameter's defaults and max, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by focusing on tool discovery rather than direct data retrieval.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't name alternative tools, the use case is clearly scoped to situations requiring browsing multiple tool options.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description responsibly adds behavioral context beyond that: parallel fan-out across sources, patent soft-failure after an API sunset, empty sections meaning real 'no data' rather than bugs, and resolved:false with notes for private companies. It also discloses sources_used/sources_failed semantics, which is exactly the kind of runtime behavior an agent needs.

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

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

The description is very long, but the length is justified by the absence of an output schema and the tool's many response sections. It front-loads purpose and routing guidance before enumerating fields, and each clause adds distinct information. It could be slightly better organized with headers, but no sentence is wasted.

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, a simple 2-parameter schema, and no output schema, this description is exceptionally complete. It documents all major output sections, failure modes, source fallbacks, and input-resolution behavior. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the description does not need to compensate for undocumented parameters. It still adds value by giving concrete examples (AAPL, 0000320193, Moderna), clarifying that type='company' and type='ticker' behave identically, and explaining how company-name resolution works through SEC EDGAR. This goes just beyond what the schema states.

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 high-signal example queries and immediately states the tool's function: a full cross-source profile of a US public company in one parallel call. It is clearly distinct from sibling tools like deep_research or resolve_entity by naming exact output sections and source families. The verb 'profile' plus the explicit scope makes the purpose unambiguous.

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

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

It explicitly instructs to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view. It also defines acceptable input shapes, notes that private companies return resolved:false, and states that 'type' accepts either value interchangeably. This gives the agent clear routing rules with concrete alternatives and conditions.

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

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

Annotations already provide destructiveHint=true, so the description does not need to repeat that. The description adds no additional behavioral traits beyond stating that it deletes. The mention of 'clearing sensitive data' is more about usage context than behavior.

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

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

The description is very concise: two short sentences with no unnecessary words. It is front-loaded with the action and immediately followed by usage guidance.

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 (1 parameter, no output schema, full annotations), the description covers the necessary information: what the tool does, when to use it, and how it relates to sibling tools. No gaps are evident.

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

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

The single parameter 'key' is fully described in the schema ('Memory key to delete'). The tool description repeats this without adding new meaning, so it does not add value beyond the schema.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and it distinguishes itself from siblings like 'remember' and 'recall' by implying that it is the inverse operation.

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 scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also pairs the tool with 'remember' and 'recall,' giving context. However, it does not explicitly state when not to use this tool.

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

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

Annotations already indicate safety (readOnly, idempotent, non-destructive). Description adds process details: fetches page, extracts title/description/links, emits standard markdown. No contradictions.

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

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

Two dense sentences plus a bullet list of use cases. No filler, each part adds value.

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

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

Simple tool with strong annotations and clear description. Covers purpose, output format, usage scenarios. No output schema needed.

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

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

Schema description coverage is 100%, so the schema documents both parameters. Description adds minimal extra (default and max for max_links). Adequate but not enhanced.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL'. It explains the benefit for AI crawlers and distinguishes from sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases: indexing a client's site, drafting your own, or auditing competitors. Lacks explicit when-not-to-use, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds context that the output consists of language codes and names specifically for 3-word output, which is helpful beyond annotations.

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

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

Single sentence front-loads the key information without wasted words. Perfectly sized for the tool's simplicity.

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 parameters, comprehensive annotations, and an output schema (not shown), the description sufficiently explains what the tool does. No gaps remain for a listing 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?

No parameters exist, so the description need not add parameter details. Baseline for 0 params is 4; the description explains the overall purpose, which complements the empty schema.

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

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

Description clearly states the tool lists supported languages for 3-word output with code and name. Verb 'list' and resource 'supported languages' are specific. Siblings include no other language-listing tools, so differentiation is inherent.

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

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

The description implies usage context (before using 3-word output tools) but provides no explicit guidance on when to use or not use this tool versus alternatives. For a tool with no parameters, explicit usage cues are minimal but present.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by specifying the returned fields and default behavior (active subscriptions), though it doesn't detail pagination or limits.

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

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

Two sentences with zero wasted words: first sentence states purpose and return fields, second provides usage guidance. Front-loaded and highly efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, return data, usage context, and default behavior. Fully adequate for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with a clear description for the single parameter. The description mentions 'active' but doesn't add new semantic meaning beyond what the schema 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?

Specifically states 'List the caller's active subscriptions' with a clear verb and resource. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by indicating it's a listing operation.

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 this to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use the tool and its practical purpose.

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 are minimal (all hints false), so the description carries the full burden and delivers strongly. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), that the tool is free and doesn't count against quota, that filing without an account returns a claim_token for later status checks, and that the team reads digests daily with direct roadmap impact. This goes far 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 but every sentence earns its place: purpose, when to use, when not to use, token behavior, rate limits, and impact. It is front-loaded with the core purpose and then logically expands. No fluff or repetition of the schema.

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

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

Given the tool has 4 parameters, a nested object, and no output schema, the description compensates fully. It covers the return value (claim_token), rate limiting, scope boundaries, and intended usage patterns. An agent has everything needed to decide when and how to invoke this tool correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds extra value beyond the schema by explaining the claim_token lifecycle (filing returns it, passing it back later reads resolution status), typical message length ('1-2 sentences typical'), and a 2000-char max, though the schema already covers most parameter details.

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 verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all sibling tools, which are research/information tools, by positioning it as the channel for reporting issues about Pipeworx tools themselves.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: tools from other MCP servers should be filed elsewhere. This is model guidance with both inclusion and exclusion criteria.

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

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

Annotations already indicate readonly, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching window (5min-1h), and self-aggregating nature. 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 about 100 words, front-loaded with the core function, and efficiently organized into use cases and technical notes. Every sentence 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?

For a simple tool with one optional parameter and no output schema, the description adequately covers return values (top tools, top packs, total call volume) and caching. However, it could briefly describe the structure of the response, but given the tool's simplicity, this is a minor gap.

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

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

Schema description coverage is 100%, with the parameter 'window' fully explained in the schema. The tool description only mentions windows briefly, adding no new semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window,' providing a specific verb and resource. It clearly distinguishes this tool from siblings by focusing on trending calls from other agents, which is unique among the listed siblings.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming popular tools, and aligning use cases. While it doesn't explicitly name alternatives or state when not to use it, the use cases provide clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral context: the fill check against live CLOB depth, the semantic anchor similarity threshold, the partition filter for placeholder slugs, and the fact that opportunities may be skipped. There is 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 relatively long but every sentence adds value. It is well-structured: starts with a summary, then details each mode, then explains filters and fill check. While it could be slightly more concise, it is still efficient 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 checks, two modes, fill analysis), the description covers the essential aspects: modes, response structure, fill check, and custom sizing reference. Lacks a detailed breakdown of the return object fields, but the tool has no output schema and the description still provides enough context for an agent to understand what it returns.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics: it explains that no arguments triggers a trending scan, that event accepts slugs or URLs, and that topic uses a seed question. It also provides examples. This added value justifies 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific behaviors, and the verb 'find' plus the named techniques make the purpose unambiguous. It is distinct from sibling tools like polymarket_fill_risk.

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

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

The description explicitly states when to use no arguments (trending scan), when to use event (for a specific market), and when to use topic (cross-event scan). It also provides a recommendation ('event recommended for a specific market') and warns when not to trade based on fill check. This is above and beyond typical guidelines.

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 as false. The description adds substantial behavioral context: caching (1h at KV level), detailed output structure (by_segment, diagnostics), and explanation of edge properties and filtering knobs. No contradictions with annotations.

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

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

The description is long but well-structured: it front-loads the purpose, then breaks into segments and knobs. Every sentence adds value. While slightly verbose, the detail is justified given the tool's complexity (9 parameters, multiple model families). The structure aids readability.

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

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

With no output schema, the description fully compensates by explaining the response structure (by_segment with three categories, diagnostics, edge properties like edge_pp_net, kelly_fraction). It also covers caching, filtering knobs, and practical notes on Fed data. Comprehensive for an agent to understand inputs, outputs, and behavior.

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

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

Schema coverage is 100% with all 9 parameters having descriptions. The description goes beyond by explaining the purpose of each knob in detail, e.g., min_liquidity drops thin-book opportunities, and providing practical advice like 'bump for very thin partitions; drop to 0 if you have a smarter fill model.' This adds meaningful value for correct parameter usage.

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 and specifically states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on disagreement with Pipeworx data and providing a holistic opportunity view.

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

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

The description includes explicit usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It details the three model segments and the available knobs for filtering, giving clear guidance on when to use the tool. However, it does not explicitly mention when not to use it or compare directly to alternatives.

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

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

Annotations already indicate readonly, openWorld, idempotent properties. Description adds extensive details: 60-day TTL, snapshot creation on cache-miss, response structure with tracked/expired/snapshot_dates arrays, and decay computed from daily closes.

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?

Well-structured and front-loaded with core purpose. Uses clear labeled sections for response fields. Slightly lengthy but each part is informative; no redundancy.

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

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

Given 2 params, no output schema, and rich annotations, the description thoroughly covers the response format (three arrays), explains limitations (60-day TTL, snapshot availability), and provides interpretation guidance (trend, decay, lifespan). Complete for agent use.

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

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

Schema fully describes both parameters (days, window) with defaults and ranges. Description adds context like 'snapshot family' and explains the meaning of window (which polymarket_edges window family). Adds marginal value over schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge longevity and distinguishes itself from sibling polymarket_edges by focusing on temporal 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?

Implies usage when historical edge behavior is needed, contrasting fresh vs. old edges. Does not explicitly state when not to use or name 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?

Discloses order-book walking, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and warns about partial basket fills creating directional risk. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and description 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?

Description is relatively long but densely informative with clear sections for modes and parameters. Every sentence adds value; slight redundancy in repeating 'Realizable-vs-theoretical' but justified for 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?

With no output schema, description details all return values for both modes, including per-leg fill details and risk warnings. Covers input options, behavior, outputs, and usage guidance comprehensively for a complex risk-check tool.

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

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

Schema coverage is 100%, but description adds meaning: explains default values, mode-specific interpretation of size_usd (max spend vs target proceeds vs settlement notional), and side default auto logic for basket. Provides context beyond schema.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with explicit return fields. Differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills convert arb to directional position).

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 only declare readOnly/openWorld/idempotent/non-destructive, but the description discloses matching logic, compatibility codes, null temporal_alignment semantics, fee treatment, and skipped-leg counters. It adds substantial behavioral context beyond annotations.

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

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

Front-loaded with purpose, modes, and response; uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). It is long and enumerates many codes, but the density is earned given the absence of an output schema and the need to warn about non-tradeable spreads.

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 3-optional-param tool with no output schema, the description covers modes, response contents, compatibility flags, fee caveats, skipped comparisons, and temporal-alignment null semantics. An agent has enough to call it correctly and 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%, baseline is 3, but the description enriches each parameter: topic maps to ten named shortcuts, and the explicit parameters 'override the topic-mapped side.' This adds usage semantics well 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?

Opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This distinguishes it from sibling Polymarket-only tools like polymarket_edges or polymarket_arbitrage by naming both venues and the same-question scope.

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

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

Clearly explains two invocation modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate, and cautions that pre-mapped does not mean tradeable. It doesn't name sibling alternatives explicitly or give when-not-to-use exclusions, so it stops short of 5.

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

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

Annotations provide safety traits, and description adds scoping context and behavior when key is omitted. No contradiction.

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

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

Two sentences, front-loaded with 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?

For a simple tool with one optional parameter and good annotations, description fully covers behavior and use case.

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 parameter fully; description adds that omitting key lists all keys, which is useful nuance beyond schema.

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

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

The description clearly states the verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly states when to use (look up previously stored context) and pairs with 'remember' and 'forget' as alternatives. Also mentions scoping.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds a key behavioral detail: setting mark_read:true flags events as read, affecting subsequent calls. 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, well-structured paragraph with four sentences. Each sentence contributes uniquely: purpose, return content, filter options, mark_read side effect, and alternative access. No wasted words.

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

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

Despite lacking an output schema, the description sufficiently explains the return value (source, citation_uri, payload). All five parameters are covered, and no nested objects require further detail. Complete for a retrieval tool with comprehensive 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 has 100% coverage with descriptions. The description enriches by giving an example for type ('sec_8k') and clarifies that since filters on fired_at >= timestamp. Adds value beyond schema without redundancy.

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 'Pull fired events from your subscription feed' with specific return fields (source, citation_uri, raw payload) and filtering options. It distinguishes itself from sibling tools like list_subscriptions by focusing on alert retrieval.

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

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

The description notes that polling works fine and provides an alternative API endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool versus siblings, though no similar sibling exists for alerts.

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 convey readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, soft-fail for patents, and the return format (changes grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

The description is well-structured and front-loaded with example queries. Each sentence serves a purpose: it defines the tool's scope, explains the fan-out, details parameters, summarizes output, and points to an alternative. No unnecessary 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?

Given the complexity of fanning out to multiple data sources and the lack of an output schema, the description covers the key aspects: data sources, fallback, parameter formats, and return structure. It omits details like pagination or rate limiting, but overall provides sufficient context for an agent to use the tool correctly.

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

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

Input schema descriptions cover all three parameters (type, since, value) with 100% coverage. The description adds value by providing examples of relative shorthand for since ('7d', '30d', '3m', '1y') and suggesting '30d' or '1m' for typical monitoring, enhancing practical usage beyond the schema.

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

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

The description clearly states the tool returns a change feed for a company over a recent time window, combining SEC filings, news, and patents. It provides example queries like 'What's new with X' and explicitly distinguishes itself from the sibling tool entity_profile, which returns 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?

The description provides explicit guidance on when to use this tool vs. entity_profile for static needs. It also explains the fallback behavior for news sources (GDELT preferred, GNews when rate-limited) and recommends typical monitoring values for the since parameter (e.g., '30d' or '1m').

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 storage as key-value pair scoped by identifier and persistence duration (auth vs. anonymous). Annotations provide idempotentHint=true but description adds context about overwriting behavior and session boundaries, adding value beyond annotations.

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

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

Three sentences, front-loaded with purpose, no redundant phrasing. Each sentence earns its place without 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 key-value save tool with no output schema, the description covers purpose, usage, and behavioral nuances. Lacks mention of return value (e.g., success confirmation) but agent can infer from context. Nearly complete.

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

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

Schema coverage is 100% so baseline is 3. Description provides example keys ('subject_property', 'target_ticker') which adds marginal value but does not significantly exceed what schema already conveys.

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 'Save data...to reuse later' with a specific verb and resource. Distinguishes from siblings via reference to 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 'Use when you discover something worth carrying forward' and pairs with recall/forget. Also differentiates persistent vs. 24-hour memory based on authentication status.

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 bar is lower; the description adds significant context beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, source-labelled identifiers, and internal cascading through multiple lookup endpoints. This is exactly the kind of behavioral disclosure that helps an agent interpret results.

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 trigger examples and a clear usage directive, and every major paragraph conveys necessary nuance. However, it is dense and at times run-on, with long parenthetical asides that could be tightened without losing meaning.

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 responsibility of explaining return behavior, and it does: candidate lists, `unresolved` fields, source labelling, identity spine contents, and failure/degradation handling. For a lookup tool with two parameters and rich output, this is a complete enough picture for an agent to invoke it correctly.

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

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

Schema coverage is 100%, but the description substantially enriches both parameters: it explains the enum values, gives input formats (ticker, CIK, ISIN, brand/generic name), provides an ISIN-to-LEI mapping example, and warns against passing full noun phrases for bonds. This goes far 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 uses a specific verb-resource pair — 'resolve a user-spoken NAME to the canonical/official identifiers' — and lists concrete trigger phrases and supported entity types. It clearly differentiates this tool from siblings like entity_profile or compare_entities by framing it as the ID-resolution entry point.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID,' giving the agent a clear decision rule. It also explains edge-case behavior — when a name matches multiple instruments it returns figi_candidates rather than asserting — which tells the agent when the tool's output is intentionally non-definitive.

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. The description adds valuable context: it probes each entity, ranks by score, and returns detailed metrics (score, confidence, signal density). This goes beyond annotations.

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

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

Three sentences: purpose, process, and use case. No extraneous information. Every sentence adds value, making it concise and well-structured.

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

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

No output schema, but the description explains what is returned (ranked list with score, confidence, signal density). Combined with full schema documentation, the description is complete and self-contained for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra meaning, such as treating the first entity as the subject for narrative and clarifying default model behavior, 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 the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe and rank. It distinguishes from sibling tools by specifying multi-entity comparison and ranking, which ai_visibility_check likely does not do.

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

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

The description provides a use case example and implies when to use (competitive audits) but does not explicitly state when not to use or give alternatives. However, it is clear enough that agents can infer differentiation from 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 provide readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: external calls to deps.dev and bundlephobia, potential 5-30s delay on new versions, partial failure handling (sources_failed). 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?

Single paragraph but well-structured: purpose first, then usage, return details, limitations, edge cases. No redundancy, each sentence adds value. Slightly long but justified by tool complexity.

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

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

No output schema, so description fully covers return structure: summary block, per-advisory detail, links, alternative versions. Also addresses error handling (sources_failed) and ecosystem scope. Comprehensive 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 has 100% coverage with descriptions for both parameters. Description adds extra meaning: scoped packages example and default behavior for version. Also explains return fields, indirectly aiding 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?

Description uses specific verb 'scan' and resource 'npm package' with clear purpose: determining if a package should be added. Differentiates from sibling tools (e.g., resolve_entity) by focusing on npm ecosystem and composite check.

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

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

Explicitly states when to use: when agent asks about safety/popularity/size/cost. Mentions limitations: NPM only in v1, suggests other ecosystems fall under deps.dev:version directly (though not naming specific tool). Lacks explicit alternative tool names.

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 as safe. The description adds concrete technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag, and return of character offsets and similarity scores. 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 yet information-dense, covering purpose, use case, pairing, and technical details in a few sentences. Every sentence adds value without repetition.

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

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

Despite no output schema, the description explains return values (passages, offsets, scores). It covers use cases, limitations (200K chars), technical model, and integration hints. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces parameter meanings (text max chars, query examples, limit range) and adds context about how they interact with the embedding process, slightly enhancing understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with examples like SEC 10-K and article, and explains its value. It distinguishes itself by focusing on internal search of already-fetched text, which contrasts with siblings that may search external sources.

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 using this tool when the record is too large for the prompt, and suggests pairing with ask_pipeworx_grounded. While it doesn't list alternatives or when-not-to-use, the context is strong and practical.

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

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

Annotations indicate idempotentHint=true, but the description says 'Returns the new subscription id', implying a new resource each time; no clarification on idempotency. However, it discloses auth requirements, SMS caps, webhook auto-disable, and subscription type details, adding significant value beyond the annotations.

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

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

The description is well-structured with bullet points and examples, front-loading the main purpose. While somewhat lengthy, each sentence provides necessary context for correct tool invocation.

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, nested objects, no output schema), the description covers all relevant aspects: subscription types, filters, delivery channels, auth, limits, and failure behavior. Lacks only partial idempotency clarification.

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

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

Schema coverage is 100%, so baseline is 3. The description adds detailed examples for each subscription type's params and explains delivery channel behaviors (e.g., webhook signing and auto-disable), providing extra meaning beyond the schema.

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

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

The description clearly states the verb ('Create') and the resource ('proactive monitoring subscription to a live-data event stream'), and specifies it returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and recent_alerts by emphasizing proactive, push-based monitoring.

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 prerequisites (Pipeworx OAuth account), lists supported types with example filters, and describes delivery channels with limitations. Does not explicitly state when not to use (e.g., for one-time queries), but the context is clear enough.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral details: results are drawn from a live catalog, can be filtered by topic, and response structure includes exact tool calls. No contradictions with annotations.

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

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

The description is relatively long but front-loaded with alternative phrasings and a clear purpose. Each sentence adds value, though minor tightening could be possible. Structure is logical: alternatives, purpose, output description, usage guidance.

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

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

For a simple tool with one optional parameter and no output schema, the description thoroughly explains the return format (category-bucketed examples with exact tool+arguments) and use cases (onboarding). It is complete for the agent to select and invoke correctly.

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

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

The single optional 'topic' parameter is well described in the schema. The description adds examples of valid topics and clarifies that omitting it yields a broad spread, which aids agent understanding beyond the schema.

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

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

The description clearly states the tool's purpose as the onboarding entry point for new users, returning example questions with exact tool calls. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by focusing on discovery rather than direct answers.

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 to use this tool FIRST when unsure of what Pipeworx can do, and to learn how to call meta-tools. It provides clear context but does not elaborate on when not to use alternatives.

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

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

Describes deactivation (not deletion) and historical event preservation, adding context beyond annotations which indicate idempotent and 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?

Two concise sentences with front-loaded purpose and no waste.

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

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

Fully covers ownership, behavioral side effects, and schema details for a simple single-parameter tool.

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

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

Schema coverage is 100% with parameter description already in schema; description adds no new semantic detail for the parameter.

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

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

Description clearly states it cancels a subscription by ID, distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement and deactivation behavior, guiding when to use and when not.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the two routing paths (SEC EDGAR fast path vs. grounded pipeline) and the exact semantics of could_not_verify, including the verification_error field and that it must not be treated as evidence. It also defines unsupported, adding meaningful behavioral context without contradicting annotations.

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

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

The description is longer than average but each sentence delivers operational value—examples, routing, return values, and error interpretation. It is front-loaded with natural-language triggers and ends with the efficiency rationale, though some redundancy exists around 'grounded pipeline' and 'structured actual 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?

With no output schema, the description thoroughly explains the verdict enum, the pipeworx:// citation, and the reasoning component. It also clarifies critical edge cases (could_not_verify vs. unsupported) and routing behavior, making the tool self-sufficient for a 2-parameter, no-output-schema configuration.

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 tolerance_pct parameter already includes detailed semantics such as valid range, override behavior, and default cap. The main description adds minimal parameter-level detail (only 'exact percent-delta math' in the financial path), so the baseline 3 applies.

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

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

The description opens with natural-language phrasings ('fact check', 'verify the claim that…') and clearly identifies the tool as claim verification against authoritative sources. It explicitly differentiates the SEC EDGAR/XBRL financial path from the general grounded pipeline, distinguishing it from sibling 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?

It states an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides important guidance on interpreting could_not_verify versus unsupported. However, it does not name sibling alternatives or specify when not to use it, so it falls short of a 5.

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

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

Annotations already declare the tool safe, idempotent, and non-destructive. The description adds value by specifying the output shape (center + 3m×3m bounding box). It does not disclose potential errors or precision, but for a simple read operation, 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?

A single, front-loaded sentence with an example. Every word is necessary, no filler. Excellent conciseness.

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

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

Given the tool's simplicity, rich annotations, full schema coverage, and presence of an output schema, the description provides all necessary context for correct invocation and understanding of the result.

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

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

Schema coverage is 100% and the schema already includes an example. The description's example is redundant. No additional meaning is provided for the 'words' parameter beyond what the schema offers, so it meets the baseline of 3.

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

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

The description uses a specific verb ('Convert') and resource ('3-word address'), clearly distinguishing this from its sibling 'coords_to_words' which does the reverse. The example and output details ('lat/lon centre + 3m×3m bounding box') solidify the purpose.

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

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

The description implies usage by stating the conversion direction, but does not explicitly mention when not to use or point to the sibling for the reverse. However, the context of a straightforward conversion makes the usage clear, and the sibling list provides the alternative.

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