Data Fulton

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds useful behavioral context: the default model is free, Anthropic requires BYO key, and the tool returns per-model data. 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 a single paragraph of 3 sentences, each conveying important information: purpose, model options, return structure, and use cases. It is front-loaded and avoids unnecessary detail, though bullet points could improve 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?

Given no output schema, the description explains the return format (per-model score, confidence, signals, raw_response + combined view). It covers main functionality but omits potential error scenarios (e.g., invalid API key, model unavailability). The annotations mitigate some need for behavioral description. Overall adequate for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds value beyond the schema by explaining the default model ('Workers AI Llama-3.3-70b (free)'), clarifying the _apiKey parameter's purpose, and providing examples for the entity parameter. This helps the agent understand parameter usage better.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/topic and scores visibility (0-100). It specifies the default model and optional Anthropic probe, distinguishing it from sibling tools like ask_pipeworx or deep_research which serve different purposes.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional _apiKey parameter. However, it does not explicitly contrast with sibling tools or mention 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 cover read-only, open-world, idempotent, and non-destructive behavior, so the description needs less safety disclosure. It adds meaningful runtime context: the tool routes across 5,798 tools and 1,517 sources, fills arguments automatically, and returns a structured answer with citation URIs. This goes beyond the annotation flags without contradicting them.

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

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

The description is much longer than necessary and contains garbled, spliced sentences, especially in the final alternatives section where the deep_research guidance repeats itself and the ending trails off awkwardly. Important information is front-loaded, but the structure would be confusing for an agent and the text needs cleanup.

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

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

For a single-parameter routing tool with strong annotations and no output schema, the description covers domains, example phrasings, returned artifacts such as structured answers and citation URIs, and sibling routing. It does not specify failure behavior or exact output format details, but the schema examples and annotation coverage make it sufficient for an agent to call 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 description coverage is 100%: the 'question' parameter is described as a natural-language request with aliases, and examples are already present in the schema. The description restates examples and acceptable question forms but adds no syntax, formatting, or alias-preference details beyond the schema, so the 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 states a clear verb and resource: ask_pipeworx routes a natural-language question to the right verified-source tool and returns a structured answer with stable pipeworx:// citation URIs. It differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research for specific alternatives, and it begins with 'PREFER OVER WEB SEARCH' plus a concrete list of covered domains such as SEC, FDA, FRED/BLS, USPTO, and clinical trials.

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

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

It gives explicit trigger phrases like 'what is', 'look up', 'get the latest', and 'how much', and says to use it even when web search could answer. It also gives when-not-to-use guidance: choose ask_pipeworx_grounded for citation-only answers, deep_research for broad multi-part questions, and it notes that breaking-news routing is already handled.

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, and the description does not contradict these. It adds valuable behavioral context: this is a live experimental edge, candidates are tested on outcome evidence, and the tool falls back to nothing because it is a full working router. This transparency about its beta nature and current matching behavior goes 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 longer than minimal but each sentence contributes meaningful context: identity, experimental nature, current state, usage guidance, and relationship to the stable router. It is front-loaded with the key identity and avoids redundancy, though it could tighten some phrasing.

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 rich annotations and full schema coverage, the description sufficiently explains what the tool does, when to use it, and how it differs from ask_pipeworx. It references the same response shape as ask_pipeworx, but since there is no output schema, a bit more detail about the expected return format would make it fully complete.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters and their alias relationships. The description adds only that the arguments are identical to ask_pipeworx, which is helpful but does not meaningfully expand on parameter semantics beyond what the schema provides.

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

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

The description states this is a beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It clearly differentiates it from the stable ask_pipeworx by emphasizing the experimental routing improvements, so an agent knows exactly what this tool is and how it differs from siblings.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving clear usage context. It also notes the current state (no active candidate) and that results are compared against the stable router, though it does not explicitly state when to prefer the stable ask_pipeworx instead.

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 true and destructiveHint false, and the description adds substantial behavior beyond them: exact success payload shape, the full refusal_reason enum with five specific failure modes, the evidence-as-verbatim-quote guarantee, the internal routing mechanism (5,798 tools across 1517 sources), and the cost differential versus the sibling. This is model-rich behavioral disclosure appropriate for a grounding-critical tool.

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

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

Dense but zero-waste: the lede carries the distinguishing value proposition, followed by mechanics, exact return/refusal shapes, usage rule, and cost tradeoff — each sentence adds new decision-relevant information. The length is justified by the absence of an output schema; the return format and refusal enum must live in prose. Front-loaded with the highest-stakes differentiator.

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

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

Despite having no output schema, the description fully specifies both success and refusal return contracts, enumerates all refusal reasons, states the routing behavior, gives cost guidance, and names the exact scenarios that warrant this mode over its sibling. For a read-only, single-parameter query tool, nothing an agent needs to call and interpret it correctly is missing.

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

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

Schema coverage is 100% — all six parameters are documented aliases (question, query, q, prompt, text, input) with clear descriptions in the schema. The description adds no param-level guidance, but none is needed since the schema already fully documents the single meaningful parameter. Baseline 3 is correct.

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+mode: 'Hallucination-resistant answer mode for high-stakes reads.' It then explicitly contrasts with ask_pipeworx ('Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains'), which distinguishes it from its closest siblings without ambiguity. An agent knows exactly what this tool is for after the first sentence.

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 when-to-use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains (financial verdicts, legal claims, medical lookups, public statements) and an explicit when-not-to-use with the economic rationale ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'). This gives the agent a decision rule, not just a vibe.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, which the description aligns with. It adds extensive behavioral detail: parallel fan-out, resolution logic, low-confidence handling, closed market detection, spread warnings, cancellation rule parsing, and blocking mechanisms. 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 lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and every sentence adds value. For the tool's complexity, the length is justified, though minor trimming could improve 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?

No output schema, so the description fully explains return values, including response shapes for market, analysis, evidence, resolver contract, parent event, news fields, safety mechanisms, and cancellation rules. Covers edge cases (low-confidence, closed markets, wide spreads) thoroughly, making it 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 coverage is 100%, and the description adds significant meaning: explains each parameter's purpose (market slug/URL/question text), the depth enum ('quick = 2-3 evidence sources, thorough = full fan-out'), and include_raw (default false, when to use true). This goes 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 function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), distinguishing it from siblings like ask_pipeworx or polymarket_edges by focusing on comprehensive bet research.

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

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

Explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly state when not to use or mention alternative tools, the provided sibling names and the comprehensive nature of the description imply this is the go-to for bet research.

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

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

Adds significant behavioral context beyond annotations: details data sources for company (SEC EDGAR/XBRL, specific financial metrics) and drug (FAERS, FDA, trials), explains sorting by primary metric, and mentions citation URIs. 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?

Dense with information but slightly verbose. Front-loaded with example queries. Every sentence adds value, though some redundancy could be trimmed.

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?

Complete for a tool with 2 parameters and no output schema. Explains input, data returned per entity type, citation URIs, and sorting. No gaps.

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

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

Schema coverage 100%, description adds meaning: explains what each entity type returns and gives concrete examples for 'values' parameter (e.g., '["AAPL","MSFT"]'), including format and constraints.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' Uses specific verb 'compare' and resource types. Distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison replacing sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and notes efficiency gains ('Replaces 8–15 sequential lookups'). Clear guidance on when to use.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the data source (Fulton County Open Data) and the exact fields returned. 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, each concise and front-loaded. The first sentence states the core purpose immediately, and the second explains the output and next step. No wasted words.

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

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

Given no output schema, the description adequately explains what is returned (resource_id, name, description, category, update date). It does not cover error handling or empty results, but for a search tool with annotations, 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 coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond what the schema already provides for the parameters (limit, query, offset). It mentions keyword search but no extra format 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 clearly states the action ('Search'), the specific resource ('Fulton County Open Data catalog of open datasets'), and the method ('by keyword'). It also lists the return fields, distinguishing it from sibling tools like 'metadata' which likely operate on a specific resource_id.

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

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

The description explains what the tool does and how to use the results (pass resource_id to other tools). However, it lacks explicit guidance on when to prefer this tool over alternatives or when not to use it. Still, the context is clear for a search function.

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

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

Annotations already mark this read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavior beyond those hints: it returns verbatim evidence with confidence, source, fetched_at, gaps[], never invents answers, includes contradictions[] for standard/thorough, and semantically excerpts long records. It also discloses latency expectations and the conditional uri resolvability of citations. No contradiction with annotations.

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

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

The description is long but appropriately detailed for a complex tool, and it front-loads the most decision-critical facts: account requirement, free signup, paid thorough depth, and the fallback alternative. Some redundancy with the input schema's depth parameter text prevents a perfect score, but no sentence is filler.

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

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

Even with no output schema, the description fully covers what the agent receives, how findings are sourced and cited, how gaps and contradictions are handled, when to prefer alternatives, and how long the call takes. An agent has enough context to select and invoke this tool correctly without additional inference.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by linking depth choices to account/pricing requirements and expected latency, and by clarifying that the question parameter supports broad/multi-part questions where decomposition is the point. It does somewhat duplicate the schema's depth explanations, hence not a 5.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call', and explicitly distinguishes itself from open-web search. It also differentiates from the ask_pipeworx siblings by positioning itself for broad/multi-part questions and naming the single-lookup alternative.

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

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

Gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'). It even provides a fallback condition tied to account status: if not signed in, use ask_pipeworx. This is model decision-quality guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, ensuring the agent understands it's a safe read operation. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context about the return format. No contradictions.

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

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

The description is front-loaded with purpose and usage, followed by a domain list and return details. It is effective and well-structured, though slightly verbose. Every sentence adds value, but could be tightened slightly.

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 role as a discovery mechanism, the description fully covers what it does, when to use it, what it returns, and how to call it. No output schema is needed since the description explains the return format. All 6 parameters are fully documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions aliases for the query parameter but adds minimal new meaning beyond the schema's own descriptions and examples. The aliases are already listed in the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific data domains (SEC filings, FDA drugs, etc.) and uses specific verbs like browse, search, look up, discover. This distinguishes it from sibling tools, each of which has a different function.

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 guidance on when to use: 'Use when you need to browse, search...' and 'Call this FIRST when you have many tools available and want to see the option set.' Provides alternatives implicitly by directing to this tool as the discovery entry point.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description richly adds runtime behavior: parallel fan-out across SEC/XBRL/USPTO/USAspending/FDA/DOL/GDELT/GLEIF, patent API sunset soft-fail, expected empty fda_products for small-molecule companies, empty-section-as-real-no-data semantics, and resolved:false handling for private companies. 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?

Clearly front-loaded with query examples and the core 'full cross-source profile' purpose, and every caveat is substantive. However, it is one very long single paragraph of semicolon-separated sections and conditions; a structured list would make the dense output inventory far easier for an agent to parse.

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

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

For a read-only aggregation tool with no output schema, the description inventories every returned section, all source fallbacks, failure expectations, accepted input shapes, and edge cases like private companies and empty data sections. An agent has nearly everything needed to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with both type and value already documented including ticker/CIK/name examples and interchangeable type values. The description largely restates those input forms, adding only the private-company resolution outcome, so it adds marginal 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 names a specific verb+resource: building a full cross-source profile of a US public company in one parallel call. Query examples like 'tell me about X' and 'brief me on Tesla' make the intent unmistakable, and the enumerated output sections differentiate it from single-purpose lookups and 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 gives an explicit precedence rule: ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also clarifies behavior for private companies and source fallbacks, but it does not explicitly contrast against siblings like resolve_entity or compare_entities, so it stops just short of full when-not guidance.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context on why deletion is appropriate (stale context, sensitive data) beyond annotations.

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

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

Two sentences, front-loaded verb 'Delete', no waste. Every sentence adds value.

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

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

Simple tool with one parameter, no output schema. Description covers purpose, usage guidance, and relationships to siblings completely.

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 description for 'key' parameter. Description adds no additional parameter meaning beyond 'by key' which mirrors 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 'Delete a previously stored memory by key.' Specific verb (delete) and resource (memory by key). Distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, task is done, or clear sensitive data.' Mentions pairing with siblings for context.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive. The description adds that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This provides useful 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?

The description is only two sentences, front-loaded with action and purpose, then details the output format and use cases. Every sentence is valuable and concise.

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

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

The description covers the output format ('single text blob', 'standard llms.txt markdown format'), mentions what it extracts, and lists use cases. It adequately addresses the tool's functionality given the lack of an output schema.

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

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

Schema coverage is 100%. The description adds meaning by specifying 'Full URL' for the url parameter and the default/max values for max_links. This adds value beyond the schema alone.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL for AI crawlers. It specifies the exact action (generate) and resource (llms.txt file), and distinguishes from siblings by focusing on this specific output format.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention when not to use or directly differentiate from siblings like 'scan_competitor_ai_presence', 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 indicate safe read operation. Description adds return fields (id, type, params, etc.) and mentions default active subscriptions. 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 concise sentences, no redundancy. Front-loaded with purpose, then return info and 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 simple schema and no output schema, description fully covers purpose, behavior, return values, and usage context.

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

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

Schema coverage is 100%; parameter is described in schema. Description doesn't add extra meaning beyond schema, meeting baseline.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more' or 'find an id to cancel'. Provides clear context and alternative actions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds transparent disclosure of what metadata is returned (columns, types, row count, etc.), providing useful behavioral details beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the main action and includes an example. 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?

Despite having no output schema, the description lists all key return fields (columns, types, row count, category, last-updated). For a simple tool with one parameter, this is fully adequate.

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 one parameter documented as 'Dataset id, e.g., 'ey9v-j62i'.' The description includes the same example. While clear, it does not add meaning significantly beyond the schema.

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

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

The description clearly states the tool retrieves schema and metadata for a dataset by resource_id, listing specific fields (columns, types, row count, category, last-updated). It distinguishes from sibling tools like 'datasets' which list datasets rather than metadata of a specific one.

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 tells when to use (when needing dataset metadata) and provides a concrete example resource_id. It does not explicitly mention when not to use or name alternatives, but the specificity implies appropriate use 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?

With all annotations false (readOnlyHint=false, etc.), the description carries the full burden and excels. It discloses the claim_token flow, rate limiting ('Rate-limited to 5 per identifier per day'), zero quota cost, and that the team reads digests daily. No contradiction with annotations 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 lengthy but every sentence serves a purpose: purpose, use cases, exclusions, token mechanics, rate limit, and quota cost. It is well-structured and front-loaded with the core purpose. Slight verbosity is justified by the tool's complexity.

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

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

Given no output schema, the description adequately explains return behavior (claim_token and later status check). It covers scope, input guidance, rate limits, quota, and reads/responses. Everything an agent needs to use the tool correctly is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds valuable operational detail: exact claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and message content guidance ('don't paste the end-user's prompt'). This enriches 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and enumerates specific use cases (bug, feature/data_gap, praise). It explicitly distinguishes itself from siblings by restricting scope to Pipeworx tools and naming alternatives for other MCP servers.

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 when-to-use criteria (bug, feature, data_gap, praise) and a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' It also advises describing issues in terms of Pipeworx tools/packs and not pasting end-user prompts, giving concrete usage guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds that data is cached for 5min-1h, derived from CF analytics-engine, and contains no PII. This fully discloses behavioral traits beyond annotations.

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

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

The description is compact (4-5 sentences) with a clear front-loaded statement, followed by bullet-point use cases and additional notes. Every sentence adds value with no redundancy.

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

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

Without an output schema, the description adequately explains return values (top tools, packs, volume) and caching behavior. It could specify output format more explicitly, but is sufficiently complete for an AI 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% and the parameter description already explains the window enum and its meaning. The main description reiterates the window options without adding new semantics, so it meets the baseline but does not exceed.

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 trending data (top tools, top packs, call volume) over a window. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on aggregate usage by other agents.

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

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

The description explicitly lists three specific use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It also contrasts window lengths for different needs, providing clear guidance on when 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?

Adds extensive behavioral context beyond annotations: monotonicity checks, partition sum, Jaccard similarity filter, placeholder filtering, fill check against CLOB depth. No contradiction with readOnlyHint=true.

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?

Detailed but well-structured with clear mode breakdowns. Slightly longer than necessary but every sentence adds value. Front-loads key info.

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

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

No output schema, but description comprehensively covers response fields, edge cases (placeholder slugs, low similarity), fill check, and references to other tools. Covers all modes and limitations.

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

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

Schema coverage is 100%, and description supplements with additional context: event accepts URLs, topic searches related events, and explains internal processing for each parameter.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly guides when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scan. It also explains fill check condition and references polymarket_fill_risk for custom sizing.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds detailed behavioral context beyond annotations, such as caching (1h at KV level), response structure (by_segment, diagnostics), and tradeable-edge 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 dense and well-structured, front-loading the core purpose and then detailing model families, opportunity fields, knobs, and diagnostics. Every sentence adds value, but it is somewhat long; a more concise version could be achieved without losing critical information.

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

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

Despite no output schema, the description thoroughly explains the response structure: top-level segments (by_segment), fields within each opportunity (edge_pp_net, kelly_fraction, etc.), tradeable-edge knobs, and diagnostics. It provides complete context for an agent to understand 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?

Input schema covers 100% of parameters with descriptions. The description adds extra context for some parameters (e.g., slippage_pp rationale, min_partition_leg_kelly explanation), but since schema coverage is high, a score of 3 is appropriate.

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

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

The description clearly identifies the tool as scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and specifies the resource ('Polymarket markets'). It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx data discrepancies.

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 the tool is built for 'what should I bet on today' and helps agents discover opportunities without paging through hundreds of markets. It provides context on usage but does not explicitly compare to sibling tools or state when not to use, though the specificity implies appropriate contexts.

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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing behavioral traits: it uses daily snapshots, has a 60-day TTL, may have gaps, computes decay from daily closes (not intraday), and provides a detailed response structure. This level of transparency fully informs the agent of the tool's 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 front-loaded with the purpose and uses structured sections (Args:, RESPONSE:, LIMITS:). It is dense but every sentence contributes to understanding, especially given tool complexity. Could be slightly more concise, but the structure makes it 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?

Despite no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and key fields (edge_pp_net, trend, decay_pp_per_day, etc.). It also covers limitations (TTL, snapshot gaps, intraday vs close). This is comprehensive for the tool's purpose.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the purpose of 'days' as lookback with default and clamp (though schema already states clamp 2-30), and 'window' as snapshot family with defaults. It clarifies that window determines which snapshot family to read, providing context beyond the schema's brief descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It uses specific verbs ('track', 'answers') and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge listing.

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

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

The description gives context for when to use the tool by contrasting fresh vs. old edges ('a 3-week-old wide edge is a different trade'), implying it's for assessing decay. However, it does not explicitly state when not to use it or name alternative tools for other use cases, such as when raw edge data is needed (which would be polymarket_edges).

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

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

Annotations indicate read-only, idempotent, non-destructive; description confirms read-only check. Discloses walk-the-ladder behavior, return fields, risks like forced directional risk and thin legs, with 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?

Description is verbose and dense with examples and warnings. While informative, it could be more concise by grouping technical details or using bullet points. Front-loading is adequate.

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 details return fields for both modes (e.g., top_of_book, vwap_fill_price, per-leg fill, thin_legs, forced_directional_risk). Explains capture ratio and profit_usd, making the tool self-contained.

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 parameters with descriptions (100% coverage), but the description adds extra context: auto-side logic for baskets and size_usd interpretation as settlement notional. This adds value beyond schema.

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

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

The description clearly identifies the tool as a realizable-vs-theoretical edge check against live order-book depth, with distinct single-market and basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying it's a pre-action risk 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: before acting on polymarket_arbitrage signals or edges above ~$500. Explains why partial basket fills convert arb into unhedged positions, and specifies required parameters (market or event) and defaults.

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

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

Even with readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: matching is keyword/word-overlap based rather than source-verified, compatibility codes can be non-empty even when pairs are returned, temporal_alignment_unknown is not confirmation of alignment, Kalshi fees are not modeled so spreads are gross, and unclassified legs are never paired. These disclosures go well beyond the structured annotation hints and do not contradict them.

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

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

The goal and primary modes are front-loaded, and the detailed safety-field inventory earns its place because there is no output schema to carry that burden. However, the description is long and repeats a few points, such as both modes using the same matcher and the temporal_alignment_unknown caveat appearing in multiple forms. It is structured and readable, but not maximally concise.

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

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

Given there is no output schema, the description is unusually complete: it names the main response elements, explains each safety code, describes when pairs are skipped or low-confidence, and discloses the gross-spread fee caveat. It covers subtle edge cases like temporal alignment ambiguity, non-equivalent bet shapes, and unclassified legs, so an agent can invoke the tool and interpret its results with minimal guesswork.

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

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

Schema coverage is 100%, so the schema already documents each parameter, but the description adds interaction semantics: `topic` selects a pre-mapped macro, the event ticker/slug override the mapped side, and both paths use the identical matcher. Example values like 'KXFED-26OCT' and 'fed-decision-in-june-825' help an agent construct inputs. The description does not explicitly state what happens if no parameters are supplied, which is a minor gap.

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

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

The opening sentence names a concrete deliverable: the cross-venue spread between Kalshi and Polymarket for the same resolving question. The description then specifies two modes, the matching logic, and the response shape, so an agent knows exactly what the tool produces. It is clearly distinct from generic single-venue or edge tools because it targets this specific Kalshi-vs-Polymarket comparison and disclaims tradeability.

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 separates the two invocation modes — pre-mapped `topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug` — and states that both run the same matcher with the same disclosures. It also warns that most pre-mapped topics currently return compatibility warnings, which sets correct expectations. It does not explicitly compare against sibling tools like polymarket_arbitrage, so it lacks a full when-not-alternative statement.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that results are returned as JSON and notes SoQL clauses should omit the leading '$', which is a behavioral detail beyond annotations. It 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 two sentences: the first explains the tool's action and inputs, the second states the output. It is front-loaded and contains no extraneous details, making it easy to parse quickly.

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

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

With 7 parameters, 1 required, full schema coverage, and no output schema, the description sufficiently covers the tool's purpose, usage pattern, and output format. It provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with individual parameter descriptions. The description adds context by grouping parameters into SoQL clauses and pagination, and clarifies the syntax convention (omit '$'), enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool runs a Socrata SoQL query against a specific dataset by resource_id, giving an example. It specifies the verb ('run a query') and resource ('dataset'), and lists query capabilities (where/select/group/order/limit/offset). This is specific and distinguishes from sibling tools like 'datasets' which list available datasets.

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

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

The description explains the tool is used to query dataset data, but does not explicitly state when to use it versus alternatives or provide exclusion criteria. It implies its purpose but lacks explicit usage guidance, such as 'use datasets to find resource_id, then use query to fetch data'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds scoping by identifier and pairing with sibling tools, but omits behavior on missing key.

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 concise, well-structured, and front-loaded with essential information.

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

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

Covers retrieval, listing, scoping, and pairing; no output schema but tool is simple; slight gap on return format but still 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 coverage is 100% with parameter description; description reinforces that omitting key lists all keys and adds context for usage scenarios.

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

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

Clearly states it retrieves a saved value by key or lists all keys, distinguishing it from siblings like remember and forget.

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

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

Explicitly describes when to use (look up stored context) and implicitly contrasts with remember and forget for saving and deleting.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by describing return fields (source, citation_uri, payload) and the effect of mark_read. Could mention ordering or absence of events.

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

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

Concise and well-structured. Each sentence adds information. Front-loaded with purpose. No redundant or unnecessary text.

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

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

Describes return values sufficiently given no output schema. Mentions polling and alternative REST access. Does not cover ordering or behavior when feed is empty, but adequate for a simple read 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 covers all 5 parameters with descriptions. Description adds real-world examples (type: 'sec_8k') and explains the practical use of mark_read for incremental reads. Exceeds schema alone.

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

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

Clearly states the tool pulls fired events from a subscription feed. Uses specific verb 'Pull' and resource 'fired events'. Distinguishes from sibling 'list_subscriptions' which lists subscriptions, not events.

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

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

Provides guidance on filtering by type and since, and explains the mark_read parameter. Mentions polling works and gives an alternative REST endpoint. Does not explicitly exclude scenarios or compare with siblings beyond implicit differentiation.

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

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

Annotations already indicate safe, idempotent read operations. The description adds significant behavioral context: it fans out to multiple sources, mentions that PatentsView API sunset May 2025 so it soft-fails, and describes the return structure (changes[] grouped by source, total_changes count, citation URIs). This goes well beyond annotation information.

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

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

The description is dense and front-loaded with purpose, but it is a single long paragraph. While every sentence adds value, it could be slightly more structured with line breaks for readability. Overall efficient.

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

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

Given no output schema, the description explains return structure. It covers all 3 parameters, mentions fallback and soft-failure, and distinguishes from the most relevant sibling. The tool's complexity is well addressed.

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, but the description adds value: it explains that since accepts ISO date or relative shorthand, provides examples for value (ticker or CIK), and gives a default recommendation for since. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states that this tool provides a change feed for a company, covering SEC filings, news, and patents within a time window. It distinguishes itself from sibling tool entity_profile by noting that entity_profile is for static profiles. The description uses specific verbs like 'what's new with X' and explains the data 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 tells when to use this tool (for 'what's new' queries) and when not to (use entity_profile for static profiles). It also mentions fallback behavior for news (GDELT→GNews) and provides guidance on the since parameter with recommended default value.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradiction with annotations.

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

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

Four efficient sentences: core function, usage trigger, pairing guidance, storage details. Front-loaded with the most important information, no wasted words.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, behavior, persistence rules, and paired tools completely. No gaps.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds example values in parentheses but doesn't provide new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples of what to store. It distinguishes itself from siblings recall and forget by directly mentioning them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides example use cases. Also tells when to use alternatives (recall, forget) and clarifies session persistence differences between authenticated and anonymous users.

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds substantial behavioral detail: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous matches returning figi_candidates rather than asserting, unresolved identifiers listed explicitly, ISIN-to-LEI resolution, and support for instruments that never have a ticker. No contradiction with annotations.

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

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

The description is dense and long, but nearly every clause carries useful information about behavior, coverage, or caveats. It is front-loaded with the purpose and key usage instruction, and it organizes into recognizable segments (supported types, enrichment notes). It is not a concise one-liner, but the length is justified by the tool's complexity.

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

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

For a tool with no output schema, the description is exceptionally complete. It explains what identifiers are returned, what happens when resolution is ambiguous or fails, how enrichment degrades, what inputs are accepted, and why the tool replaces multiple manual lookups. An agent has enough context to call it correctly in nearly any intended scenario.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the meaning of the type enum, what each identifier type means, and adding critical value-parameter nuance such as passing the exact issuer name for bonds and avoiding trailing security-class words. This meaningfully supplements 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 opens with concrete example queries and states the core purpose: resolving a user-spoken NAME into canonical/official identifiers that other tools require. It lists supported entity types and the specific identifier systems involved (SEC CIK, GLEIF LEI, OpenFIGI FIGI, RxNorm RxCUI), which clearly distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides detailed input-format instructions, including what not to pass for bonds. However, it does not explicitly name sibling tools it should be preferred over or state when to use an alternative, so it stops short of full when-to-use/when-not-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it probes with ai_visibility_check, returns a ranked list with score, confidence, signal density per entity, and requires an API key for Anthropic model. 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 two sentences, front-loaded with the main functionality. It is concise and informative without unnecessary words.

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

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

Given the tool's complexity (4 params, no output schema, sibling tools), the description is complete: it explains inputs, behavior, output format, and use case. Output is described adequately.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds semantic value by explaining that the first entity is treated as the subject and rest as competitors, and that context is shared across probes.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It provides a concrete use case example and distinguishes itself from sibling tools like ai_visibility_check (which is the underlying probe) and compare_entities.

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 it is useful for competitive AI-marketing audits and gives an example question. It implies when to use this tool for side-by-side comparison, but does not explicitly state when not to use or mention 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?

Discloses behavioral details beyond annotations: bundlephobia's first measurement can take 5-30 seconds, sources_failed will list timeouts, partial failures degrade gracefully. Annotations already indicate read-only, open world, idempotent, and non-destructive, so the description adds critical real-world 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?

Description is front-loaded with the core purpose, then details sources, usage, ecosystem scope, and error handling. Every sentence is informative and concise, with no filler. It is structured logically and appropriately sized.

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

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

No output schema exists, but the description enumerates the return fields (summary block, per-advisory detail, links, alternative versions). It covers input, behavior, error handling, and ecosystem limitations. The tool is complex with multiple sources, and the description provides a complete mental model.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds that scoped packages like '@types/node' are accepted for the 'package' parameter, which is not in the schema's description. For 'version', it reinforces the default to latest. It adds modest 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?

Describes a composite check for npm packages combining deps.dev and bundlephobia data, clearly stating the purpose: a one-call 'should I add this npm package' check. Distinguishes itself by specifying the scope (NPM ecosystem) and the exact questions it answers (safe, popular, small, cost of adding). It is distinct 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?

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also gives clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Provides guidance on partial failures and timing (bundlephobia 5-30s first measurement).

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 technical specifics beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. Consistent with readOnly and idempotent hints.

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

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

Concise 6-sentence description, each sentence adds value. Front-loaded with purpose, then usage and technical details. No extraneous content.

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

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

Covers all essential aspects: purpose, when to use, output characteristics (passages with offsets, similarity scores), technical constraints, and pairing with sibling. No output schema needed for this level of detail.

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. Description adds minor context for query (natural-language examples) but largely rephrases schema. Baseline 3 with slight improvement.

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

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

Clearly states the tool performs semantic search inside a fetched record, with examples like SEC 10-K and articles. Differentiates from sibling tools like ask_pipeworx_grounded by describing pairing.

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

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

Explicitly says when to use: when the record is too large for the prompt. Explains benefits (saves context, returns passages with offsets) and pairs with a sibling tool (ask_pipeworx_grounded).

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 idempotentHint=true but description does not clarify idempotency (e.g., duplicate creation behavior). However, it adds context beyond annotations: account requirement, type-specific parameters, delivery constraints (SMS cap, webhook auto-disable), and return of subscription id. 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 somewhat lengthy but well-structured: it front-loads the core purpose and return value, then details types and delivery options. Every sentence provides necessary context. Could be slightly more compact, but effective.

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

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

Given 3 parameters, nested objects, no output schema, and no annotations beyond safety hints, the description is remarkably complete. It covers return value (subscription id), supported types, delivery channels, and constraints (phone verification, daily cap, webhook signing and auto-disable).

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 significantly expands on each parameter: type enum explanations with concrete examples, params object with detailed structure per type, and delivery object with constraints (phone verification, email pattern, webhook signing secret). This adds substantial meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the action (create) and resource (subscription), and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and explains delivery channels and constraints (SMS verification, daily cap, webhook signing). However, it does not explicitly state when to use this tool versus alternatives like recent_alerts, but the creation vs. retrieval distinction is implicit.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: it returns category-bucketed examples with tool calls, and the topic parameter behavior. No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and clear purpose, but is somewhat lengthy. However, every sentence adds value, and the structure is logical. Slightly longer than ideal but effectively organized.

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

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

Given no output schema, the description adequately explains return format (category-bucketed examples with tool calls). It mentions the live catalog and meta-tools. Lacks details on response size or pagination, but covers essential context for onboarding.

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

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

Schema coverage is 100% and the description enriches the parameter meaning by listing example topics in plain language (finance, pharma, etc.) and explaining that omitting gives cross-category spread, which goes beyond the schema's brief description.

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

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

The description clearly states the tool returns category-bucketed example questions about Pipeworx capabilities, with exact tool and argument shape. It distinguishes itself as the onboarding entry point, with specific triggering queries like 'what can I 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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists example queries. It also specifies that omitting topic gives full spread and passing topic focuses the results, providing clear when-to-use guidance.

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

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

Discloses ownership and soft-delete behavior beyond annotations. No contradictions.

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

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

Two sentences, no fluff, front-loaded purpose.

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

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

Complete for a simple tool with one parameter and no output schema; covers purpose, ownership, and side effects.

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%; description adds context that id comes from 'subscribe', adding 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?

Clear verb+resource ('Cancel a subscription by id'). Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Describes ownership enforcement and deactivation behavior, implicitly specifying when to use. No explicit alternatives but context is clear.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses the two-path routing (SEC EDGAR vs grounded pipeline), explains the meaning of each verdict, and includes an important caller warning about 'could_not_verify' not being evidence. No contradiction with the read-only/idempotent/open-world 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 well-organized and front-loaded with user intents. It earns its length by covering routing, verdict meanings, and a critical caller warning, though a more compact phrasing could tighten it without losing information.

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

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

With no output schema, the description fully explains the return formats (verdict types, actual value, citation, reasoning) and the failure semantics ('could_not_verify' vs 'unsupported'). It covers the entire workflow, making it complete for a tool of this complexity.

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

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

Input schema covers 100% of the parameters with rich descriptions for both 'claim' and 'tolerance_pct'. The description itself adds minimal parameter-level semantics beyond the schema, so it neither overpays nor underpays relative to the schema 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 explicitly states the tool's purpose as natural-language claim verification against authoritative sources, with a clear verb ('verify') and resource ('claims'). It distinguishes itself from sibling tools by detailing the specific verdict-based output and the SEC EDGAR fast path for financial claims.

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 clear trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing context and mentions that it replaces sequential calls, but it does not explicitly name alternatives or provide when-not-to-use scenarios.

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