Czso Cz

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds: default model, BYO key for Anthropic, return structure (score, confidence, signals, raw_response). No contradictions.

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

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

Four sentences, front-loaded with purpose, no filler. Every sentence adds value.

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

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

No output schema, but description explains return structure. All parameters described. Annotations cover safety and idempotency. Complete for a probe 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 100% of parameters with descriptions. Description adds context (default model, billing implications for _apiKey, response shape). Adds meaningful 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?

Specific verb+resource+scope: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility'. Clearly distinguishes from siblings (e.g., ask_pipeworx) by focusing on AI visibility audits.

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?

States use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Implicitly not for general Q&A, but lacks explicit exclusions or alternatives.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover core safety and behavior. The description adds substantial value by explaining that it routes to one of 5,564 tools across 1,462 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also warns about its single-call nature, implying no multi-source fan-out. Minor improvement would be explicitly stating that it may return no answer if no source matches, but overall closure is strong.

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 key preference directive in the first sentence, followed by a list of data domains and usage patterns. It is well-structured but slightly longer than necessary; some redundancy exists (e.g., repeated 'Look up' examples). Every sentence earns its place, but trimming a few examples could tighten it without losing clarity.

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

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

Given the tool's complexity (routing among thousands of sources) and the absence of an output schema, the description does a good job of explaining what it returns (structured answer with citation URIs). It could be slightly more explicit about failure modes (e.g., what if no source matches) or constraints (e.g., max response time). However, the rich annotations and clear usage guidelines largely compensate, making it sufficiently complete for an agent.

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

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

Schema coverage is 100% with a single required parameter (question) and five aliases. The description does not add any new meaning to the parameter beyond what the schema provides – it merely reinforces that the tool accepts natural language questions. The baseline of 3 is appropriate since the schema already fully documents the parameter and its aliases without needing extra elaboration.

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 is a router for factual questions over authoritative structured data sources, listing specific domains (SEC filings, FDA drugs, etc.) and distinguishing it from web search. It uses a specific verb ('routes to the right one of 5,564 tools') and resource ('authoritative structured data with citations'), making its purpose unmistakable relative to siblings.

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

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

The description provides extensive usage guidance: it explicitly prefers this tool over web search for factual questions, lists example query patterns ('what is', 'look up', etc.), and gives concrete examples. It also clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions) and what to use for breaking news, making it easy for the agent to decide.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description reveals the tool's beta nature, the mechanism of candidate routing improvements, and that it is a fully working router with no fallback. It also notes the current status of no active candidate, providing transparency about its experimental edge.

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

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

Three sentences total: first defines the tool's identity and scope, second clarifies current operational state, third gives usage guidance. Every sentence is essential, front-loaded with identity and purpose. No redundant or extraneous information.

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

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

The tool is complex (beta router over 5K tools) with no output schema. The description covers identity, state, usage, and behavioral guarantees. It omits details on the response format or how routing improvements are evaluated, but since it refers to ask_pipeworx for sameness, the coverage is sufficient for agents relying on sibling tool descriptions.

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 clear definitions for all six parameters (question and its aliases). The description adds no parameter-specific detail beyond stating 'same arguments' as ask_pipeworx. Baseline 3 is appropriate as the schema already handles meaning thoroughly.

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

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

The description explicitly states it is the beta version of ask_pipeworx, a universal router with the same 5,564 tools and arguments. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded by focusing on experimental routing improvements, giving a clear, specific purpose.

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

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

The description directly tells when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate) and that results are compared against the stable router, implicitly guiding the agent away if stable behavior is preferred.

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 return format with refusal reasons, cost of an extra LLM call, and extraction behavior beyond what annotations (readOnly, idempotent, openWorld) already state.

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 yet comprehensive; every sentence earns its place. Purpose, behavior, return format, use cases, and trade-offs are front-loaded and logically ordered.

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

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

Given no output schema, the description fully covers return format and error states. Tool is well-situated among 30+ siblings with clear differentiation and complete usage guidance.

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 already describes all 6 parameters as aliases for 'question'. Description adds no parameter meaning beyond the schema, which is acceptable but not value-added.

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?

Explicitly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results, clearly distinguishing it from the sibling ask_pipeworx.

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

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

Provides explicit when-to-use ('when answer will be cited or acted on...must not invent facts') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), plus cost trade-off.

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

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

The description extensively details behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract, parent event extractor, news field fallback mechanisms, safety short-circuits for low-confidence and closed markets, liquidity warnings, and resolution-rule risk. It adds substantial context not present in the annotations, which already declare read-only, idempotent, and non-destructive behavior.

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

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

The description is very long (multiple paragraphs) and contains extensive detail. While the first sentence effectively front-loads the purpose, the overall verbosity reduces conciseness. Every sentence does earn its place given the tool's complexity, but a more structured format (e.g., bullet points) could improve readability without losing information.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description is exceptionally complete. It covers inputs, outputs, error states (low confidence, closed markets, wide spreads), resolution-rule risk, and edge cases like fallback in news fields. It ensures an agent can understand and invoke the tool correctly with minimal ambiguity.

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 three parameters. The description adds significant meaning: clarifying that 'market' accepts slug, URL, or question text; explaining the 'depth' default and behavior; and detailing when to use 'include_raw' (e.g., for recomputing deltas). This goes beyond the schema's basic descriptions.

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

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

The description starts with a specific verb and resource: 'Research a Polymarket bet'. It explains the tool resolves the market, classifies, fans out, and returns evidence. The examples and usage scenarios make its purpose unmistakable. It implicitly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on single-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?

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to trust analysis by instructing to inspect market_match_confidence. However, it does not explicitly state when not to use the tool versus siblings, which is a minor gap.

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

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

Description adds significant behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions.

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

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

Single paragraph, front-loaded with trigger phrases, each sentence adds value. Could be slightly more structured but efficient overall.

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 explains return format (paired data + citation URIs, sorted). Parameters are fully explained, and usage is clear. Complete for tool complexity.

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

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

Schema coverage is 100%, and description adds meaning by explaining enum values (company vs drug) and value format (tickers/CIKs vs drug names, min/max items). Adds source details beyond schema.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, lists trigger phrases like 'compare X and Y', and distinguishes from sequential lookups. Verb+resource is clearly defined.

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' and describes data sources per entity type. No explicit when-not or alternatives beyond preference, but context is clear.

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

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

Annotations already provide safety profile (readOnly, idempotent, etc.). Description adds context about being catalog layer only and the type of information returned, which is useful beyond what annotations capture.

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 efficient sentences: first lists what the tool returns, second clarifies when to use siblings. No wasted words.

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

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

Despite no output schema, the description lists the fields returned, making the behavior clear. Combined with excellent annotations and schema, the description is complete for this single-parameter tool.

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

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

100% schema coverage. The description mentions the parameter 'kod' but does not add substantial meaning beyond what the input schema already describes. 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?

Clearly states it returns full catalog metadata for a dataset by id, listing specific fields and explicitly distinguishing from data_summary and get_data which provide actual numbers.

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 to use this for catalog metadata and to use data_summary/get_data for actual numbers, naming specific alternative tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds context by calling it 'cheap' and explaining what it returns, which helps the agent understand its lightweight nature.

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

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

Three sentences, no wasted words. First sentence lists outputs, second gives usage context, third adds parameter detail. Front-loaded with purpose.

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

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

For a simple read-only tool with two parameters, the description adequately covers what it does, when to use it, and parameter behavior. No output schema needed; description explains return fields.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds that version (verze) auto-resolves from catalog if omitted, providing extra semantics beyond the schema.

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

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

The description clearly states the tool returns a cheap content summary for a ČSÚ dataset, listing specific fields (number of data cells, time range, per-dimension counts, timestamps). It distinguishes from sibling tools by explicitly recommending use before get_data to gauge size.

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

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

Explicitly says 'Use this before get_data to gauge size, since full datasets can be large.' Also explains that version is auto-resolved if omitted, providing clear when-to-use and behavioral 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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds extensive behavioral context: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop fields, and citation_uri. It explains how depth options affect behavior (gap recovery, iterative hops, contradiction scanning), large record excerpting, and expected timing. 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 quite long and contains dense detail, which is necessary for a complex tool. However, it could be more concise; some details (e.g., 'second-hop iteration' explanation) are repeated in multiple places. The critical information is front-loaded (account requirement, alternative tool), but the overall length may reduce readability. Still, it is well-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 the tool's complexity (2 parameters, no output schema, many behavioral nuances), the description is remarkably complete. It covers account requirements, alternatives, when to use/not, output structure (findings with fields like gaps, contradictions, hop, citation_uri), depth semantics, timing, and large record handling. Without an output schema, it fully explains what the tool returns, leaving no significant 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 description coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains the meaning of each depth enum value ('quick=3...', 'standard=3... adds a gap-recovery hop...', 'thorough=6... paid...'), notes that 'standard' is the default, and clarifies that the question can be broad/multi-part. This goes 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's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It distinguishes from siblings by explicitly noting use cases: 'for a single lookup use ask_pipeworx' and 'for BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also clarifies what it is not ('this is NOT open-web search'), providing a precise and specific verb+resource+scope.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'If you are not signed in, use ask_pipeworx instead', 'for a single lookup use ask_pipeworx', and 'for BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also mentions account requirements and depth plan restrictions, leaving no ambiguity about appropriate usage 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description goes beyond by stating that returned results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' This adds useful behavioral context about output richness and convenience, though no contradictions.

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

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

Description is well-structured with a clear first sentence, followed by a list of domains and return format. While the list of domains is somewhat lengthy (18+ items), each item is relevant and aids specificity. It is efficient for the amount of information conveyed.

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

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

Given no output schema, the description fully explains what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This covers all necessary context about output format and usability. 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 all 6 parameters documented. The description mentions aliases (query, q, task, etc.) but this is already in the schema. No additional parameter semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform data retrieval or analysis (e.g., get_data, deep_research). The verb 'discover' and resource 'tools' are precise and unambiguous.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and contrasts with retrieving a single answer.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds nuanced behavioral traits: it fans out across multiple APIs (SEC, XBRL, USPTO, GDELT, GLEIF), returns specific data fields with details (e.g., 'LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'), discloses a soft-fail for patents (USPTO sunset May 2025), and emphasizes the tool executes in a single parallel call. 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 with information but well-structured, starting with example user queries to immediately convey purpose. It is somewhat long but every sentence adds value (data sources, returned fields, limitations). A slightly more structured format (e.g., bullet points) could improve scannability, but the information density justifies the length.

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

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

Given the tool's complexity (multiple external sources, varied return data) and absence of an output schema, the description covers all essential details: input requirements, data sources, specific return fields, failure modes (patents), and the parallel execution nature. It also notes the current limitation (only company type) and provides visual context for returned URIs. This enables an agent to accurately invoke and interpret results.

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

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

Schema coverage is 100% with descriptions for both parameters (type and value). The description adds examples ('AAPL', '0000320193'), clarifies that type is currently limited to 'company', and explicitly states names are not supported. While the schema already provides baseline info, the description reinforces and provides additional context for correct usage.

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

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

The description explicitly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call' and lists all data sources and returned fields (CIK, filings, fundamentals, patents, news, LEI). Example queries like 'tell me about X' and 'company profile for Microsoft' clarify the intent. This distinguishes it from siblings like 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 instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input format (ticker or zero-padded CIK) and states 'names not supported', directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent. Description adds context about clearing sensitive data, which is beyond annotations.

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

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

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

Simple tool with one parameter and clear annotations; description fully covers use case and context.

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

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

Schema coverage is 100% with a single parameter 'key' described. Description does not add extra meaning 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 'delete', resource 'memory by key', distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clearing sensitive data. Mentions pairing with remember and recall.

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 as true, and destructiveHint false, which the description respects. The description adds behavioral detail: fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

The description is efficiently structured: purpose first, then process, then use cases. It is not overly verbose, and every sentence contributes useful information.

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

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

For a read-only, idempotent operation with two parameters and no output schema, the description covers the key aspects: input, operation, output format, and practical applications. Missing error handling details are acceptable given the tool's low complexity.

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

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

Schema coverage is 100% with descriptions for both url and max_links. The description adds value by stating the default and max for max_links and confirming the URL type, going beyond the schema.

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

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

The description clearly states the tool's action ('generate a production-ready llms.txt file'), the target ('any URL'), and the output ('standard llms.txt markdown format'). It distinguishes itself from siblings by focusing on a specific AI-indexing task not covered by other tools.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt, auditing competitor'). It does not list when not to use it, but the scenarios are clear and there are no obvious alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. The description adds that the result is a full cross-product that can be large (hundreds of thousands of cells, 1MB+) and that version is auto-resolved, providing beyond-annotation context.

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

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

Two sentences: first states purpose and format, second adds usage guidance and size warning. No redundant words, front-loaded with key information.

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

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

Describes return format (JSON-stat 2.0 with dimensions, cell counts, numbers), warns about large size, and suggests a precursor tool. Despite no output schema, this is thorough for a complex data-fetching tool.

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

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

Schema coverage is 100%. The description explains `kod` as dataset ID from `list_datasets`, notes `lang` labels are mostly Czech-only, and states `verze` auto-resolves. This adds insight beyond schema descriptions.

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

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

The description clearly states the tool fetches observations/values for a ČSÚ dataset in JSON-stat 2.0 format, with specific fields like `id`/`dimension`, `size`, and `value`. This distinguishes it from siblings like `list_datasets` and `data_summary`.

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 advises calling `data_summary` first to check `pocetUdaju` and notes auto-resolution of version. While it doesn't explicitly state when not to use, the guidance is clear and useful.

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 that API has no server-side search, which is critical behavioral info beyond annotations. Adds specific return fields. 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?

Two efficient sentences, front-loaded with purpose and key details, no wasted words.

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

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

For a simple list tool with rich annotations, it covers purpose, parameters, return fields, and API limitations. 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%, description adds case-insensitive substring matching detail and paging context, going 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?

Uses specific verb 'browse' and resource 'catalog of datasets', clearly lists return fields, and distinguishes from siblings like 'dataset_detail' via scope.

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

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

Explains filtering and paging behavior, mentions lack of server-side search, and provides context for when to use. Does not explicitly name alternative tools but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds detail about default active-only listing and return fields, but does not contradict annotations. Additional behavioral info (e.g., pagination) is not needed given annotations.

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

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

Two sentences, front-loaded with action and return fields. 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?

With one optional parameter, clear annotations, and description covering return fields and usage, the definition is complete for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, with the parameter include_inactive documented in schema. Description implicitly explains its effect by mentioning 'active subscriptions,' but adds minimal value beyond schema.

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

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

Description clearly states the action ('list the caller's active subscriptions') and specifies return fields (id, type, params, etc.). This distinguishes it 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 states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for usage, though alternatives are not directly named.

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

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

The description goes well beyond the minimal annotations (all false) by disclosing key behaviors: filing without an account returns a claim_token that can be used to later fetch resolution status, rate limiting to 5 per identifier per day, cost/free-ness, and that the team reads digests daily. It also explains the mechanism for following up on a report, which is not evident from the schema or annotations.

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

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

The description is long but well-structured and front-loaded: purpose in the first sentence, then use cases, exclusions, follow-up mechanism, and operational details. Almost every sentence earns its place, though the final motivational note about 'digests daily and signal directly affects roadmap' is slightly peripheral and could be trimmed without losing functional guidance.

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

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

For a feedback tool with no output schema and a relatively simple function, the description is unusually complete. It covers the full lifecycle: when to use, what to include, how account-less filing works, how to claim a token, rate limits, and cost. No significant gaps remain for an agent to understand how to invoke the tool correctly and what to expect.

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

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

Schema coverage is 100% with descriptive field text, so the baseline is 3. The description adds value by explaining how claim_token is obtained and used ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and it maps the type enum categories to real-world trigger scenarios. This is more than the schema alone provides, so a score above baseline is warranted.

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

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

The description opens with a clear, specific verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete categories (bug, feature, data_gap, praise) and is clearly distinct from siblings like ask_pipeworx, which is for asking questions rather than submitting feedback.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion: tools from other MCP servers should be reported to that server instead, and it tells users how to identify Pipeworx tools. This is exemplary contextual 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?

Beyond annotations (readOnly, idempotent, nondestructive), the description adds key behaviours: data sourced from CF analytics-engine, no PII, and caching 5min-1h depending on window. 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 plus bulleted list, front-loaded with purpose. Every sentence adds value; no redundancy. Could not be more concise while maintaining completeness.

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 sufficiently explains return values (top tools, top packs, total call volume). Annotations cover safety; description covers caching and data source. Complete for intended 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 has 100% coverage for the single parameter 'window', including enum and description. The description adds context on window trade-offs (hot vs steady-state), enhancing semantic clarity beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', specifying the resource (trending calls on Pipeworx) and the action (returns). It differentiates from siblings like 'discover_tools' by focusing on real-time 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 provides three explicit use cases (discovering hot sources, confirming canonical tool, aligning use case) and explains window trade-offs. It lacks explicit when-not or alternative tool suggestions, but the guidance is strong.

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

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

The description discloses behaviors beyond annotations: trending scan for top 200 markets, partition check details, fill check against live CLOB depth, semantic anchor for similarity, and placeholder filtering. No contradictions with annotations which already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint.

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 comprehensive and well-structured with sections and examples, but it is relatively long. Some technical details (e.g., semantic anchor, partition filter) could be more concise. However, the front-loading of modes and examples earns a high score.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities array, partition_check, fill check) and covers edge cases (low similarity, placeholder filtering, fill check). It is complete and self-contained for a complex tool.

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

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

Schema coverage is 100% with basic descriptions, but the tool description adds substantial value: explains mode selection, provides example slugs for event, and seed questions for topic, and details how each parameter triggers specific behavior. This goes well beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and provides concrete examples, differentiating it from sibling tools.

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

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

The description explicitly specifies when to use each mode: no args for trending scan, event for specific event slug, topic for cross-event scanning. It also warns against trading when realizable_edge_pp ≤ 0 and suggests using polymarket_fill_risk for custom sizing, providing clear context and exclusions.

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

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

Annotations already declare the tool as readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond annotations: caching at KV level keyed on all knobs, response structure including diagnostics for empty segments, and detailed model family explanations. 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 front-loaded with the purpose, but is quite verbose with multiple paragraphs detailing model families. While informative, it could be more concise by focusing on essential guidance and leaving model internals to documentation.

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 9 parameters and no output schema, the description thoroughly explains the response structure (by_segment, fed_elements, diagnostics), model families, and filter knobs. It provides sufficient context for an AI agent to understand what the tool returns and how to use it effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not repeat parameter descriptions but adds context for some parameters (e.g., 'tradeable-edge filter' for max_spread_pp). This adds some value but is not extensive beyond what the schema already provides.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear purpose 'what should I bet on today'. It is specific about the resource (Polymarket markets) and action (scanning and returning opportunities), but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 context that it is built for discovering opportunities without paging hundreds of markets, and details the knobs for filtering. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds useful behavioral details: 60-day snapshot TTL, decay computed on daily closes (not intraday), snapshot gaps due to cache misses. 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 well-structured with clear sections for response fields (tracked, expired, snapshot_dates) and limits. It is front-loaded with purpose and usage. While somewhat dense, every sentence is informative with minimal fluff.

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

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

Given no output schema, the description fully explains the response structure with field details. It covers parameters, defaults, edge cases (gaps, history bounds), and limits. Comprehensive for a telemetry 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?

Schema coverage is 100%, so parameters are documented. The description restates defaults and adds clamping info (max 30) which is consistent with schema. It explains the meaning of 'window' as snapshot family but does not add significant new semantics beyond schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('answers how long has this edge existed') and distinguishes from siblings like polymarket_edges by focusing on time-series history.

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

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

The description implies when to use (to distinguish fresh vs aged edges) and provides context with the example of a 3-week-old edge being suspicious. It does not explicitly state when not to use or name alternatives, 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 readOnly, idempotent, non-destructive. Description adds substantial behavioral detail: walks order book ladder, returns fields like top_of_book, vwap_fill_price, slippage, verdict, and explains basket mode risks. No contradictions.

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

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

Description is long but well-structured with mode sections, capitalized warnings, and front-loaded purpose. Every sentence adds information, though slightly verbose for the given 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?

Despite no output schema, description compensates by listing return fields for both modes and explaining key risks (partial fills, thin legs). Covers all necessary aspects for a complex dual-mode tool.

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

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

Schema coverage is 100%, baseline 3. Description adds meaningful interpretation beyond schema: explains side behavior in basket mode (auto from partition sum) and clarifies size_usd for basket as 'settlement notional—shares per leg, each paying $1 at resolution'. Adds value.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing two modes (single-market and basket) with specific inputs and outputs. It is precise and not a tautology.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', explaining why partial fills convert arb into unhedged directional positions. Provides clear when-to-use and consequences.

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, and idempotentHint, but the description adds extensive behavioral details: compatibility_warning conditions, temporal alignment, skipped_cross_type/subtype explanations, and the limitation that real spreads are rare. No annotation contradiction.

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

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

The description is well-structured with clear sections (modes, response, safety fields) and is front-loaded with the core purpose. While somewhat long, every sentence adds meaningful context for a complex tool.

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

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

Without an output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread, safety fields) and covers edge cases like compatibility_warning and temporal alignment. It is complete for an agent to interpret results.

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

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

Schema description coverage is 100% with each parameter described; the description elaborates on the topic list and provides explicit ticker format examples, adding 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 starts with a clear one-sentence purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains the two modes and distinguishes itself from sibling tools by focusing on cross-venue comparison rather than single-venue arb.

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

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

The description explicitly states when to use topic vs explicit ticker mode and warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. It could be clearer about when NOT to use the tool, but provides enough 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, and destructiveHint, so the description's behavioral transparency is supplemented. It adds scoping details (tied to identifier) and the listing behavior, but does not disclose additional traits like rate limits or performance. This is adequate given 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 two sentences, front-loaded with the primary action, and every sentence provides essential information without redundancy. It is efficiently structured for quick comprehension.

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 retrieval tool with one optional parameter and no output schema, the description covers the core behavior, scoping, and relationship to siblings. It is complete enough for the tool's complexity, though it could optionally mention return format; not necessary but would not harm.

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

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

The input schema covers the single parameter 'key' with 100% description coverage. The description enhances this by explaining the listing behavior when omitted and providing concrete examples (user's target ticker, address), adding value beyond the schema's minimal 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 retrieves a previously saved value or lists all saved keys, using specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from siblings by mentioning 'remember' and 'forget' and provides concrete examples of usage, making the purpose unambiguous.

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

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

The description explicitly explains when to use the tool (to look up context stored earlier) and how to list all keys (omit the key argument). It pairs with remember and forget, giving clear context, but does not explicitly state when not to use it or provide alternative tools beyond the siblings mentioned.

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 significant behavioral context beyond the annotations, including the effect of mark_read on future calls, the returned fields (source, citation_uri, payload), and the behavior of unread_only. 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 concise with three sentences, each adding value: main purpose, return fields and parameters, and an alternative access method. No unnecessary information.

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

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

Given the five optional parameters and no output schema, the description effectively covers key behaviors, return fields, and practical usage (polling, alternative endpoint), making it complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds meaning by explaining the purpose of type, since, mark_read, unread_only, clarifying filtering and the read flagging behavior, which is beyond the schema's property descriptions.

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

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

The description begins with a clear verb 'Pull' and resource 'fired events from your subscription feed', distinguishing it from sibling tools like list_subscriptions and recent_changes.

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 mentions polling works fine and provides an alternative REST endpoint, giving usage context. However, it does not explicitly state when to use this tool vs. sibling tools or when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds detailed behavioral info: the fan-out to multiple APIs, fallback logic, and accepted input formats, enhancing transparency 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 somewhat lengthy but front-loaded with example queries. Every sentence adds value, and the structure is logical. A slight reduction in verbosity 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 exists, so the description compensates by explaining the return structure (changes grouped by source, total_changes count, citation URIs). It covers input, behavior, and alternatives fully.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning: explains 'since' accepts ISO date or relative shorthand with examples, 'type' is limited to 'company', and 'value' can be ticker or CIK. This exceeds baseline.

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

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

The description clearly states the tool provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) in a single call, using example queries to illustrate. It distinguishes from the sibling tool entity_profile by specifying when to use each.

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 entity_profile instead ('when you want the static profile...'). Also explains the GDELT→GNews fallback condition and the soft-fail for patents, providing clear context for tool selection.

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

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

The description discloses important behavioral traits beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' 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?

Three concise sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple tool with 2 params and no output schema, the description covers purpose, usage guidelines, behavioral transparency, and pairing with siblings. 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 covers both parameters with good descriptions (100% coverage). The description adds contextual examples ('subject_property', 'target_ticker') and explains value types, providing additional meaning.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data' (key-value pairs). It distinguishes from sibling tools 'recall' and 'forget' by explicitly 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?

The description provides clear guidance on when to use: 'when you discover something worth carrying forward… so you don't have to look it up again.' It pairs with 'recall' and 'forget' but lacks explicit '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.

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

The annotations already declare read-only, idempotent behavior, and the description adds substantial detail beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers under `unresolved` rather than omission, source-labelled identifiers, and cascading internal lookups. 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 front-loaded with example queries and a clear purpose, and every sentence contributes meaningful information with no fluff. However, it is a lengthy single paragraph that could benefit from bullet points or section breaks to improve scannability, preventing a perfect score.

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 the absence of an output schema, the description thoroughly covers the returned identifiers for each entity type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), explains the unresolved-identifier behavior, and describes fallback behavior when external sources fail. This is comprehensive given the tool's complexity and lack of 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%, so the baseline is 3, but the description enriches parameter meaning substantially. It explains that 'value' for company can be a ticker, CIK, ISIN, or name, describes the ISIN-to-LEI mapping for non-US issuers, and gives concrete examples for drug (brand/generic names), which goes beyond the schema's one-line 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 defines the tool as resolving user-spoken names to canonical/official identifiers, listing the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI) and supported entity types (company, drug). Example queries and the directive 'Use FIRST whenever you have a name but need an ID' distinguish it from sibling tools like entity_profile 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 when to use the tool ('Use FIRST whenever you have a name but need an ID') and notes that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name specific alternative tools for overlapping scenarios, leaving a slight gap.

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-only, idempotent behavior. The description adds behavioral details: it probes entities with ai_visibility_check, ranks results, and returns score/confidence/signal density per entity. 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 two sentences with a parenthetical example, front-loading the purpose and mechanism. Every sentence adds value; 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?

The description covers what the tool does, how it works (probes, ranks), and what it returns (ranked list with metrics). Combined with schema that documents parameters and constraints (2-8 entities), it is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about entities array (first as subject, rest as competitors) which is not in schema, but other parameters like models and context are already well described in schema. Description adds only marginal 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 states the tool's purpose: compare AI visibility across multiple entities side-by-side. It specifies the action (compare), resource (AI visibility), and scope (multiple entities). It distinguishes itself from the sibling tool ai_visibility_check by being an aggregate comparison tool.

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

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

The description provides a clear use case: competitive AI-marketing audits, with an example question. It implies when to use this tool over single entity checks but does not explicitly mention when not to use or compare to other siblings like compare_entities.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds critical behavioral context: partial failures, bundlephobia first measurement timing (5-30s), and sources_failed reporting. 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 detailed but not overly verbose. Front-loaded with purpose and usage. Some redundancy in explaining return structure, but all information earns its place for completeness.

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

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

Despite no output schema, description fully explains return value structure (summary block, per-advisory detail, links, alternative versions, sources_failed). Covers edge cases, fallback behavior, and limitations. Highly complete.

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

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

Schema coverage is 100% with clear descriptions. Description adds minimal extra meaning by clarifying scoped package acceptance and version default behavior, but this is already in schema. Slight value added.

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's a composite 'should I add this npm package' check combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are well-defined, and it distinctly differs 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 says when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies NPM ecosystem only and directs other ecosystems to alternative tools.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag.

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

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

Single, well-structured paragraph with no superfluous content. First sentence captures essence, followed by usage guidance, technical details, and limitations. Every sentence is informative.

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

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

Despite no output schema, description clearly implies return content (passages with character offsets and similarity scores) and mentions truncation flag. Sufficient for agent to understand behavior and expectations.

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%; description adds value by providing query examples, clarifying text character limit, and specifying default limit (5) and max (20) beyond schema.

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

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

Description explicitly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article) and distinguishes from sibling by mentioning pairing with ask_pipeworx_grounded.

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

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

Clear context for when to use: 'when the record is too big to cram into the prompt' and benefits like saving context and returning passages with offsets. Does not explicitly state exclusions, but guidance 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 indicate idempotentHint=true and destructiveHint=false. The description adds extensive behavioral context: OAuth requirement, delivery channels, SMS cap (10/day), phone verification need, webhook HMAC signing, and auto-disable after 10 consecutive failures. No contradictions.

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

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

The description is dense but well-organized, starting with the core purpose and then detailing types and delivery options. It is slightly long but every sentence adds significant value. Could be trimmed slightly for brevity.

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 3 parameters and no output schema, the description covers return value, prerequisites, all parameter details, rate limits, error cases (auto-disable), and authentication requirements. It leaves no major 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%, but the description greatly enhances parameter meanings. It provides concrete examples for each subscription type's params (e.g., sec_8k with items), details delivery constraints (SMS cap, webhook secret), and clarifies requirements like phone verification and signing.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription ID, using specific verb and resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description specifies that a Pipeworx OAuth account is required and lists supported subscription types and delivery channels. While it does not explicitly state when not to use, the context of creating subscriptions is clear and implies alternatives like 'unsubscribe' exist.

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. The description adds that the tool returns live-sourced examples with exact tool+argument shapes, which is valuable behavioral context beyond the annotations.

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

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

The description is a single paragraph but packs all critical information: purpose, examples, argument behavior, and usage timing. It is front-loaded with common queries. Slightly verbose but effective; could be restructured for even faster scanning.

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

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

No output schema, but the description explains the output format (category-bucketed example questions with tool+argument shape). It covers when to use, how to call, and what to expect. Lacks mention of edge cases but is sufficient for an introductory 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?

The single optional parameter `topic` is described in the schema, but the description adds a list of example values and clarifies behavior ('omit for a cross-category spread'). This adds meaning beyond the schema, so above the baseline of 3.

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

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

The description clearly states it is the onboarding entry point for a new agent, returning category-bucketed example questions. It uses specific verbs ('Returns category-bucketed example questions') and distinguishes itself from siblings like ask_pipeworx and entity_profile.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when to invoke, but does not explicitly state when not to use it.

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

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

Annotations already indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true). Description adds that the row is deactivated not deleted, preserving history – a valuable behavioral detail 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, no redundant words. Action verb first, followed by two important behavioral details. Efficient and easy to parse.

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

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

For a 1-parameter tool with no output schema, the description covers purpose, constraints (ownership), effect (deactivate vs delete), and side-effect (history preserved). Could mention idempotency explicitly but annotation covers it.

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

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

Schema coverage is 100% with a clear schema description. The description adds context that the id is the one 'returned by subscribe', linking it to another tool and clarifying its origin.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes itself from siblings like subscribe (creates) and list_subscriptions (lists) by specifying resource and scope.

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

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

Clearly indicates when to use: cancel own subscription. Implicitly tells when not to: ownership is enforced, so only own subscriptions. Does not explicitly name alternative tools but context from siblings is sufficient.

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

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

Provides rich behavioral detail beyond annotations: explains the two-path pipeline (SEC EDGAR/XBRL vs. grounded), the verdict types, and crucially clarifies that 'could_not_verify' means the check did not happen and is not evidence, carrying verification_error. Also explains 'unsupported'. This adds significant context for correctly interpreting results.

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

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

The description is longer than typical but is well-structured: starts with user-phrasing examples, then core behavior, then return values and critical caveats. Each sentence adds value, though it could be tighter. The first line is somewhat dense 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 the absence of an output schema, the description does an excellent job explaining return values (verdict types, actual value, citation, reasoning) and edge cases (could_not_verify, unsupported). It covers the tool's complexity well, including the fast path vs. grounded pipeline, making it sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions tolerance_pct in the context of hallucination detection and exact percent-delta math, but does not add substantial meaning beyond the schema's own parameter descriptions. The schema already explains 'claim' with examples and 'tolerance_pct' with behavior.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific verb 'validate' and resource. It distinguishes itself from generic QA tools by focusing on fact-checking and outlines two distinct verification paths. The purpose is unambiguous and differentiable.

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 the agent needs to check whether something a user said is factually correct.' It also describes internal routing for company-financial vs. other claims and notes it replaces 4-6 sequential calls, giving clear context. However, it does not name alternative sibling tools or provide explicit 'do not use when' exclusions.

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