Zoho_crm

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: cost implications ('you pay Anthropic directly'), BYO key handling, and the fact that it probes multiple models. This adds meaningful value without contradicting 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 three sentences, front-loaded with the core function, followed by configuration details and use cases. Every sentence earns its place; no filler or redundancy.

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

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

Given the tool has no output schema, the description appropriately explains the return format. It covers purpose, usage context, defaults, and safety via annotations. It lacks explicit limitations or error conditions, but for a read-only, idempotent probe tool with well-documented parameters, this is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-level detail beyond the schema; it only re-emphasizes the default model and API key behavior already covered in the schema. The main addition is the return structure, which relates more to output than parameter semantics.

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

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

The description clearly states the tool's function: probing LLMs for what they know about an entity and scoring visibility. It uses a specific verb ('probe') and resource ('LLMs'), and specifies the output. However, it does not explicitly distinguish itself from similar sibling tools like scan_competitor_ai_presence, so it doesn't fully earn a 5.

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

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

The description provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model configuration. However, it does not mention any exclusions, alternatives, or when not to use it, falling short of the explicit when/when-not guidance that would merit a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful behavioral context beyond annotations by revealing that the tool routes across 5,529 tools, fills arguments automatically, and returns stable citation URIs. It does not discuss failure modes or rate limits, but the provided context is strong with annotations covering safety.

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

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

The description is longer than average but well-structured and front-loaded with the most important guidance. The list of example queries and explicit sibling differentiation earn their place, though a few phrases could be trimmed without losing meaning. Overall, every section serves a clear 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 general-purpose router tool with no output schema, the description fully covers when to use it, how it behaves, what output to expect, and how it compares to alternatives. The schema covers parameters, and the description adds the citation-URI output detail that compensates for the missing 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 description coverage is 100%, and the single semantic parameter 'question' is fully documented with aliases and examples. The description adds usage examples and trigger phrases, but these are more about when to use the tool than about parameter formats. Baseline of 3 is appropriate because the schema already handles parameter semantics.

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

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

The description clearly states a specific function: routes natural-language questions to authoritative data sources and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, and from web search, by positioning itself as the default entry point for factual questions.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It says 'PREFER OVER WEB SEARCH', lists trigger phrases like 'what is' and 'look up', and directs users to step up to ask_pipeworx_grounded for verbatim evidence or deep_research for multi-part questions. No alternative is left ambiguous.

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. The description adds valuable context: it is an experimental router with candidate improvements that can be enabled live, currently inactive. It also states 'Falls back to nothing — this IS a full working router,' reassuring semantic transparency about fallback behavior. 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 three sentences long, each contributing key information: what the tool is, current state, and usage guidance. It is front-loaded with the most critical fact (beta of ask_pipeworx) and avoids redundancy. Every sentence earns its place.

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

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

Given the complexity (universal router with 5,529 tools) and absence of an output schema, the description is quite complete. It specifies the relationship to ask_pipeworx, experimental nature, and current equivalence. It lacks explicit mention of return format, but references 'same response shape' as the stable tool, which is sufficient for an agent that can look up the sibling.

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

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

Schema coverage is 100% with all six parameters described as aliases for 'question', so baseline is 3. The description mentions 'same arguments' but does not add extra meaning beyond the schema. It confirms that the tool accepts the same inputs as ask_pipeworx, which is mildly useful but not essential.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes from the stable sibling by emphasizing the experimental routing improvements and current state. The verb 'ask' in the name is reinforced by 'universal router' and usage instructions.

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: 'Use it exactly like ask_pipeworx when you want the newest routing.' It contrasts with the stable router and explains the comparison process. Also clarifies that it currently matches ask_pipeworx exactly, giving concrete usage context. No alternatives are named, but the reference to ask_pipeworx serves as the alternative.

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 key behavioral traits beyond the annotations: it extracts answers only from tool results, returns a structured object with evidence and refusal reasons, and explicitly enumerates refusal categories. This adds significant context about safety, failure modes, and output guarantees that the annotations (readOnlyHint, openWorldHint, idempotentHint) do not cover. 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 information-dense yet well-structured. It opens with the core concept, then explains mechanism, return payload, usage scenarios, and cost tradeoff in a logical sequence. Every sentence adds unique value—no filler, no repetition. The length is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies the return format and all possible refusal reasons, covering success and error paths. Combined with the simple input schema (one required param with aliases) and rich annotations, the description provides a complete mental model for an agent to decide when and how to use the tool.

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

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

The input schema already covers all parameters (100% description coverage), with aliases for `question` clearly documented. The description does not add extra parameter-level meaning, but since the schema handles it thoroughly, this is acceptable. The baseline of 3 applies because the schema does the heavy lifting and the description adds no conflict or additional clarity.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource (tool results from a large routing system). It explicitly distinguishes itself from the sibling tool ask_pipeworx by describing the added grounding/evidence step, making its unique purpose unmistakable.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also names the sibling tool and highlights the cost tradeoff (one extra LLM call), providing clear decision 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?

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds extensive behavioral detail: resolver contract with market_match_confidence, short-circuit on low-confidence matches, closed-market status handling, fallback news fields with retry metadata, and resolution-rule risk (e.g., refund_50_50). This significantly exceeds what annotations convey and does not contradict them.

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

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

The description is extremely long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the core purpose, and every section delivers essential operational guidance. However, its sheer length and density push it slightly below a 5 for 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?

There is no output schema, so the description fully compensates by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news field fallback statuses, and safety statuses. It gives a complete operational picture for an agent to correctly interpret results and handle edge cases.

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% for all 3 parameters, so the baseline is 3. The description also reinforces the market parameter formats and explains fan-out behavior per classifier, but the schema already fully documents the parameters; the description adds minimal additional parameter-specific semantic 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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also explains the input formats (slug, URL, question text) and provides explicit example use cases ('should I bet on X', 'what does the data say about Y'), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides clear usage context: 'Use for "should I bet on X"...' and lists specific example fan-out scenarios. However, it does not explicitly name alternative tools or state when not to use this tool versus siblings, so it stops short of a 5.

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

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

The description goes far beyond the annotations by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting behavior by primary metric, and output format with citation URIs. This rich behavioral detail is not present in the readOnly/openWorld/idempotent annotations.

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

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

The description is dense but every sentence earns its place: trigger phrases, explicit preference rule, data source details, sorting behavior, and output format. It is front-loaded with high-value usage examples and avoids repeating schema content.

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

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

Given the tool's moderate complexity, no output schema, and only two simple parameters, the description is complete. It explains the parallel call advantage, data sources, sorting, fiscal-year handling, and citation URIs, leaving no major unanswered questions about invocation or expected 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%, so the baseline is 3, but the description adds meaning by explaining what each enum value pulls (10-K financials vs. FAERS/trial counts) and giving concrete examples for values. This enriches the parameter semantics beyond the schema's terse 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: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It uses specific verbs and resources and distinguishes it from sequential single-pack lookups by explicitly replacing them.

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

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

It explicitly says when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides trigger phrase examples. It also differentiates behavior for type=company vs type=drug, giving clear context for both use cases.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses the account requirement, paid tier, latency, return packet structure (gaps[], contradictions[], citation_uri, hop), semantic excerpting, and the fact it never invents answers. This is rich behavioral context that annotations alone do not provide.

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

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

The description is well-structured and front-loaded with the account requirement and alternative tool, but it is verbose and somewhat repetitive (e.g., gaps[] and contradictions[] are mentioned multiple times). Every sentence adds value, but the same information could be stated more tightly.

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

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

With no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop), prerequisites, limitations (not open-web, poor for breaking news), and latency. This gives the agent complete context for selection and invocation.

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

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

The schema already describes both parameters, but the description significantly enriches them: it explains the depth enum values (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop), and clarifies that question can be broad and natural language. This goes well beyond the baseline schema coverage.

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 does grounded multi-source research across Pipeworx's 1455 structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and sibling ask_pipeworx, giving a precise 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 explicitly says 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx', as well as for breaking news. It also tells agents to use ask_pipeworx if not signed in, providing both positive and negative usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral value by explaining the return format (top-N tools with names, descriptions, and full input schemas) and the 'no second schema lookup needed' trait, which is not in annotations. No contradiction exists.

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

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

The description is longer than the ideal two-sentence example but every sentence contributes: purpose, domain list, return value, and usage guidance. It is front-loaded with the core verb and includes practical examples. Could be tightened slightly, but it is not verbose.

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

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

For a discovery tool with no output schema, the description covers what the tool does, when to use it, what it returns, and the key benefit (directly callable results). The absence of output schema is compensated by the explicit return description. It omits potential rate limits or query processing details, but these are not critical given the read-only, idempotent nature.

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 detailed parameter descriptions and aliases, so the baseline is 3. The description only subtly references parameters (e.g., 'top-N' implying limit, 'describing the data or task' for query), but does not add significant meaning beyond the schema's own documentation.

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

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

The description clearly states the tool's purpose with a specific verb ('Find tools') and resource ('tools by describing the data or task'). It distinguishes itself from siblings by listing the domains it covers and its role as a discovery tool, ensuring no confusion with the many specialized 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 states when to use this tool ('Use when you need to browse, search, look up, or discover what tools exist') and even instructs to 'Call this FIRST when you have many tools available'. This provides clear context and differentiates it from directly calling sibling tools.

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

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

The description discloses numerous behavioral details beyond annotations: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields with structure (e.g., recent_filings up to 5 with URIs, fundamentals sorted by period_end), and mentions the USPTO PatentsView API sunset with soft-fail behavior and GDELT→GNews fallback. This far exceeds the minimal safety implied by readOnlyHint and gives the agent a clear picture of 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 long (about 170 words) and begins with six example queries, some of which are redundant for conveying purpose. While all information is relevant, the dense, single-paragraph structure and repetitive example list could be trimmed and structured (e.g., bullets for return fields) to improve readability. It is not as concise as the two-sentence get_calls example, though it is not overly verbose.

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

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

Given the tool has no output schema and two simple parameters, the description provides a thorough inventory of return fields (CIK, company name, recent filings, fundamentals, patents, news, LEI), data sources, fallbacks, and input constraints. This gives an agent enough context to invoke the tool and interpret results without needing additional documentation.

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

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

The input schema already describes both parameters with 100% coverage, including examples of ticker and CIK formats and the note about names not being supported. The description repeats the same 'Pass ticker or zero-padded CIK' guidance without adding new semantic meaning beyond schema, so it does not elevate above the high-coverage 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 the tool produces a 'full cross-source profile of a US public company' with specific verb 'profile' and resource 'US public company', plus six concrete example queries that illustrate the intended use. It distinguishes from siblings by explicitly saying it is preferred over chaining single-pack SEC/XBRL/news lookups, making the purpose and scope unmistakable.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a clear when-to-use directive. It also states 'names not supported (use resolve_entity first if you only have a name)', offering a specific alternative for a known edge case, which is strong 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 provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and operating on previously stored memories, but does not elaborate on edge cases like missing keys or irreversibility beyond what the annotations imply. It does not contradict annotations.

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

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

Two concise sentences front-load the core action and then provide practical usage guidance. No wasted words or redundancy.

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

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

For a simple single-parameter destructive tool, the description covers what it does, when to use it, and related tools. The annotations handle safety traits, and the lack of output schema is acceptable given no return value is specified. Missing edge-case behavior is not critical for this simplicity.

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

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

The schema has 100% coverage for the key parameter with description 'Memory key to delete'. The description's mention of 'by key' and 'previously stored' adds minor semantic nuance (implying existing keys), but the schema already carries the essential 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 'Delete a previously stored memory by key' with a specific verb (delete), resource (memory), and method (by key). It also distinguishes itself from sibling tools remember and recall by focusing on removal rather than storage or retrieval.

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

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

The description explicitly provides use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, giving contextual guidance on related tools and when this deletion tool is appropriate.

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, but the description adds the crucial behavioral trait that it makes an external network fetch ('Fetches the page'). It also discloses output format and that it emits a 'single text blob.' This adds context beyond annotations, such as network dependency and the standard output, though it does not detail failure modes. With annotations covering safety, this is above average.

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 four sentences, each earning its place: purpose, process, output, and use cases. It is front-loaded with the main verb and resource, and there is no filler or redundancy. Efficient and well-structured.

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

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

The tool has no output schema, so the description compensates by explaining the return value ('llms.txt markdown format'). It covers the workflow and use cases. It lacks explicit error-handling or invalid-URL guidance, but for a simple fetch-and-format tool with good annotations, this is minor. Overall complete but with slight 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 the schema fully documents both parameters. The description does not add extra meaning about parameters beyond what the schema provides; it mentions 'extracts title/description/key links' but not parameter syntax or interplay. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on outputting the llms.txt format. It also explains the process (fetches page, extracts data) and the standard format, 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 provides explicit use cases: getting a client's site indexed, drafting for your own project, and auditing competitor AI crawler view. While it does not explicitly mention alternatives or when not to use, the use cases are clear enough to guide the agent. Sibling tools like 'scan_competitor_ai_presence' imply overlap, but no exclusion is stated. Clear context without exclusions merits a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context beyond annotations by specifying that only the caller's subscriptions are returned, that active ones are shown by default, and listing the exact return fields. This is useful behavioral detail not covered by 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 verb and resource, followed by return fields and usage context. Every sentence earns its place, with no wasted words or redundant 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 simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, scope, and usage context. The include_inactive parameter is fully documented in the schema, so no additional information is needed. The description is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for the only parameter include_inactive, with a clear description of its effect. The tool description doesn't add meaning beyond what's in the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes from siblings like subscribe and unsubscribe by focusing on read-only listing. The return fields are enumerated, leaving no ambiguity about what the tool does.

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

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

The description provides explicit guidance: use this to review what you're monitoring before adding more (implying before using subscribe) or to find an ID to cancel (implying before using unsubscribe). This directly addresses when to use the tool versus alternatives among the sibling tools.

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

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

Annotations only give low-level hints (readOnly=false, etc.), but the description discloses crucial behavior: filing without an account returns a claim_token, passing that token later reads the status, the team reads digests daily, and signal directly affects roadmap. This goes far beyond what annotations alone convey, with 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 long but every sentence serves a purpose: purpose, examples, exclusions, token workflow, roadmap impact, rate limits, and cost. It is front-loaded with the core action and immediately followed by usage categories, making it easy to scan.

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

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

For a feedback tool with no output schema, the description fully explains the return behavior (claim_token, status reading), expected message format, rate limit, and cost. It also tells the agent exactly how to describe issues in terms of Pipeworx tools/packs, which is essential for correct invocation.

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

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

Although schema coverage is 100%, the description adds meaningful cross-parameter semantics, especially the claim_token lifecycle (file first, later pass the token as the only argument to read the reply). It also frames the context object as 'which tool, pack, or vertical' in a way that clarifies how to fill it.

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

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

The description opens with a specific verb phrase ('Tell the Pipeworx team something is broken, missing, or needs to exist') that clearly defines the tool's purpose. It distinguishes this feedback tool from sibling research and data tools by focusing on reporting issues/requests back to the Pipeworx team.

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 guidance by enumerating categories (bug, feature/data_gap, praise) and a clear exclusion: if the tool came from a different MCP server, file it there instead. It also notes rate limits and the 'doesn't count against quota' policy, helping agents decide when this tool is appropriate.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable context: it explains the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'). 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 and well-structured, opening with the core function, then listing use cases, and ending with technical details. Every sentence adds value, and the list format enhances readability.

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

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

For a simple read-only tool with one optional parameter, the description covers all essential contextual info: return value, time windows, use cases, data provenance, privacy, and caching. No output schema exists, but the description adequately conveys what the agent will receive.

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

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

Schema coverage is 100%, so the schema fully documents the window parameter. The description mentions the windows but does not add semantics beyond the schema's own explanation ('Shorter windows surface what's hot right now'). Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'). It explicitly distinguishes itself from siblings by focusing on what other agents are calling, which is unique among the listed 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 'Useful for' section lists three concrete scenarios, such as discovering hot data sources and confirming canonical tools. This provides clear guidance on when to use this tool versus alternatives like ask_pipeworx or discover_tools.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description goes far beyond this by disclosing internal thresholds (>3pp deviation), semantic matching (>=0.30 Jaccard), partition filtering (placeholder fraction >20% returns null), and the fill check behavior that tells the agent not to trade if realizable_edge_pp <= 0. This is exceptional behavioral disclosure.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that break down complex behavior. Despite its length, it is scannable and efficient for an agent to parse.

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

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

With no output schema, the description fully covers return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices...}'. It also explains the fill check output and when signals are actionable. Given the tool's complexity, this description is complete and self-contained.

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

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

Though the schema already provides 100% coverage with descriptions for 'event' and 'topic', the tool description adds substantial meaning: it gives concrete examples of event slugs ('fed-decision-may-2026'), explains that full URLs are accepted, and details what each mode does semantically. This elevates the schema descriptions and leaves no ambiguity about parameter values.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the tool's unique approach and explicitly mentions modes (event/topic) and the fill check. This is unambiguous and gives the agent a precise mental model.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also explains the distinction between modes and directs users to polymarket_fill_risk for custom sizing, naming an alternative. This is the gold standard for usage guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses deep behavioral details: three model families, the exact computation of edge_pp_net (after slippage), the 24h-move warning, tradeable-edge knobs, the Fed exclusion rationale, diagnostics funnel counters, and KV caching keyed on knobs. There is no contradiction with the annotations, and it provides substantial value beyond them.

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

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

The description is long and dense, but it is front-loaded with a clear purpose, then logically organized by model families, response fields, knobs, top-level structure, and caching. Every major section earns its place given the tool's complexity, though the heavy jargon (e.g., '90d FRED log-returns', 'GDELT 7d/21d') may be overwhelming for some agents. It is appropriately sized for the complexity, but not concise in a literal sense.

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

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

With no output schema, the description must explain return values, and it does thoroughly: by_segment structure, edge_pp_net, Kelly fractions, liquidity/spread/volume fields, the 24h-move warning, and _diagnostics with funnel counters. It also covers caching and the Fed note. This is a complete picture for a complex tool, with 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%, so the baseline is 3. The description adds extra semantics by explaining how knobs interact (e.g., 'min_kelly never filters [partition arbs]' and min_partition_leg_kelly applies to per-leg Kelly inside top_legs instead). This contextual guidance goes beyond the parameter descriptions, aiding selection and configuration.

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

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

The description opens with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the intended use case ('what should I bet on today'), which clearly distinguishes it from sibling tools like polymarket_arbitrage (likely focused on specific arb math) or polymarket_edge_tracker (tracking edges over time), 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 clearly states when to use this tool (opportunity discovery without paging hundreds of markets) and even mentions that Fed bets are surfaced but excluded from ranking, implying a particular use context. However, it does not explicitly name alternative tools or state when NOT to use it, stopping short of the full 'when/when-not/alternatives' bar.

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

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

The description adds substantial behavioral context beyond the annotations: 60-day snapshot TTL, reliance on daily closes (not intraday), gap interpretation (cache-miss), and the absolute-value computation for decay. These details expose data limitations and calculation semantics, providing transparency the annotations don't cover.

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

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

The description is longer than typical but every sentence adds value: purpose, mental model, argument context, response format, and limitations. It's front-loaded with the core purpose and structured with flags, though slightly verbose in the response section.

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 only 2 parameters and no output schema, the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]), calculation methodology, and historical limitations. It provides all necessary context for an agent to use the tool 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?

The input schema already provides 100% coverage for both parameters, including defaults and ranges. The description repeats this information and adds minimal context (e.g., 'lookback', 'snapshot family'), satisfying the baseline but not adding significant new 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edges.

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

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

The description implies when to use the tool (for historical edge persistence/decay analysis) and contrasts fresh vs. old edges, but it doesn't explicitly name alternatives like polymarket_edges or state when not to use it. The guidance is clear but not fully explicit with 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: it explains order-book walking, the verdict categories (clean|degraded|cannot_fill), the outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), and warns about forced_directional_risk and thin_legs. Nothing contradicts the annotations; it enriches them.

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

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

Although the description is long, it is tightly structured with mode-specific sections and every sentence carries operational value. The first line states the core purpose, and the rest is organized around single-market, basket, and usage context. There is no filler; for a tool of this complexity, the length is appropriate and front-loaded.

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

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

With no output schema, the description fully enumerates return fields and verdicts, covers both modes thoroughly, explains the risk of partial basket fills, and ties the tool to specific upstream signals (polymarket_arbitrage, polymarket_edges). It leaves no significant gap for an agent to understand when and how to invoke it correctly.

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

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

Schema coverage is 100% with already-detailed param descriptions. The description goes further by clarifying size_usd semantics in single-market mode ('max spend on buys, target proceeds on sells') versus basket mode ('settlement notional S — shares per leg; each share pays $1'), and explains the side default logic for basket mode. This adds interpretive meaning beyond the schema alone.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools by emphasizing fill risk and realizable versus theoretical edge, and it enumerates two distinct modes (single-market and basket). This is far more specific than a generic purpose statement.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why the tool is necessary (theoretical overround is not capturable on thin books) and describes the dominant loss mode. This is a model of when-to-use guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing response structure, compatibility_warning cases, temporal alignment fields, and skipped cross-type/subtype counters. It explicitly states that most pre-mapped topics currently return warnings, providing honest disclosure of the tool's real-world behavior and limitations.

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 with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Most sentences add unique value, though the extensive examples like 'Kalshi range_bucket point-in-time vs Polymarket cumulative_threshold touch-anywhere' could be condensed without losing critical meaning. The front-loaded purpose statement and sectioned format help navigation.

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 and the absence of an output schema, the description thoroughly covers the response shape (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and explains safety fields that are crucial for correct interpretation. It also explains edge cases (matched_pairs:0 scenarios) and the meaning of temporal misalignment, making it complete for an agent to understand both inputs and outputs.

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?

While the schema covers 100% of parameters, the description adds meaningful context by explaining the two mutually exclusive modes ('topic' vs explicit tickers), how overrides work, and the semantics of pre-mapped shortcuts. This goes beyond the schema's simple parameter descriptions, giving the agent deeper understanding of how to use the parameters together.

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

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

The opening sentence clearly identifies the tool as computing the cross-venue spread between Kalshi and Polymarket for the same question. This specific verb+resource combination distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects of prediction market data.

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 outlines two modes (topic shortcuts vs explicit tickers) and provides clear context for when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings and are 'pre-mapped ≠ tradeable', setting expectations for when the tool should be trusted vs when closer inspection is needed. However, it does not directly name alternative sibling tools, which keeps this at a 4 rather than a 5.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving a single value vs listing all keys when key is omitted. 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 three sentences, packs in purpose, usage, scoping, and relationships to siblings without redundancy. It front-loads the primary action and uses practical examples to clarify the 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 single-optional-parameter read tool with strong annotations and no output schema, the description fully covers purpose, usage, and scope. The return behavior (a saved value or a list of keys) is implied by the action and schema, so no further explanation is needed.

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

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

The input schema already fully documents the optional 'key' parameter, including the omit-to-list behavior, so the description's mention of the key argument adds little beyond the schema. The description does reinforce that keys were previously saved via 'remember,' but this doesn't materially expand parameter understanding. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description uses the specific verb 'Retrieve' with the resource 'value previously saved via remember,' immediately clarifying the tool's role. It explicitly contrasts with siblings by naming 'remember' and 'forget' for save/delete, distinguishing recall as the read operation.

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

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

It provides explicit use cases ('look up context the agent stored earlier—user's target ticker, an address, prior research notes') and states a clear benefit ('without re-deriving it from scratch'). It also names the companion tools remember/forget for write/delete operations, giving the agent an appropriate selection 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?

Description contradicts annotations: mark_read:true is described as flagging returned events read so the next call only shows newer ones, which is a persistent state change, while readOnlyHint=true declares the tool read-only. This is a significant conflict, overriding the otherwise useful disclosure of return fields and filtering behaviors.

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 five sentences, front-loaded with purpose, and every sentence adds value. The HTTP endpoint mention is slightly beyond tool scope but useful; no wasted words, though slightly longer than necessary for a top conciseness 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 no output schema, the description explains the return shape (source, citation_uri, raw event payload). It covers filtering, mark_read side effects, polling suitability, and an HTTP alternative. It does not mention unread_only or limit, but the schema already documents those, so the tool is complete enough for selection and invocation.

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, so baseline is 3, but the description adds meaningful enrichment: a concrete example for type ('sec_8k') and explains that mark_read:true makes the next call only show newer events, which is a behavioral consequence beyond the schema's 'flag read' wording.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly differentiates this tool from siblings like recent_changes and list_subscriptions by focusing on fired alerts from the persisted feed and mentioning filtering and read-state management.

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 clear when-to-use context: polling works, and the same feed is available via GET registry.pipeworx.io/alerts.json for scripts/dashboards, implying when to use an alternative access method. However, it does not explicitly contrast with sibling tools, so it stops short of a 5.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by detailing the fan-out behavior: SEC EDGAR filings, GDELT→GNews fallback with rate-limit/5xx handling, USPTO patents with a soft-fail due to PatentsView sunset, and the return shape (changes[], total_changes, pipeworx:// URIs).

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 front-loaded with practical use cases. It covers multiple data sources, fallback behavior, return format, and an alternative tool in a compact paragraph. Slightly long but every sentence contributes relevant detail.

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

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

Even without an output schema, the description explains the return structure (changes[], total_changes, citation URIs), input semantics, source-specific behavior, and failure modes. It is sufficiently complete for an agent to understand how to 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%, so baseline is 3. The description repeats the since format and value examples already in the schema; it does not significantly enrich parameter meaning beyond what the input schema provides.

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

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

The description clearly states a specific purpose: a change feed for a company over a time window, with concrete example queries. It also distinguishes itself from entity_profile by explicitly directing users there for static profile needs.

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 strong usage guidance with example phrasings ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' This tells the agent when to use this tool vs. a sibling.

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

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

The description adds behavioral context beyond annotations: persistence scoped by identifier, authenticated vs anonymous retention (24h), and relationship to recall/forget. It doesn't contradict the readOnlyHint=false or idempotentHint=true annotations, and the added details are meaningful.

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

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

Three sentences front-loaded with purpose, then usage, then persistence details. Every sentence contributes without redundancy.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, when to use, persistence semantics, and sibling pairing. It is essentially complete for effective selection and invocation.

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

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

The schema already fully describes both parameters with examples, giving 100% coverage. The description reinforces the key-value nature and scoping but adds only marginal semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'Save'. It distinguishes itself from siblings by explicitly naming recall and forget as complementary tools, making its 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 provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') with concrete examples. It also instructs pairing with recall and forget, clearly differentiating from alternatives.

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

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

The description goes well beyond the annotations. It explains the internal cascade of multiple lookup endpoints, the behavior of unresolved identifiers (stated explicitly under `unresolved` rather than omitted), and graceful degradation when GLEIF/OpenFIGI are unavailable. It also details the per-type source attribution (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). These are behavioral insights not present in the annotations.

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

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

The description is long but every portion serves a purpose: query examples, core purpose, supported types, source details, and fallback behavior. It is front-loaded with a barrage of natural-language examples that immediately convey the tool's domain. The length is justified given the dual entity types and the complexity of the return data, though it could be trimmed slightly without loss of meaning.

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

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

With no output schema, the description fully compensates by detailing the return values for each type: company returns CIK, LEI, FIGI, ownership, etc., with source labels and an `unresolved` field; drug returns RxCUI, ingredient, brand, and a citation. It also accounts for failure modes (degradation). This is a comprehensive specification 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?

Although schema coverage is 100%, the description adds substantial meaning. It clarifies that `value` for company can be a ticker, CIK, or company name depending on context, and specifies the input forms for drug (brand or generic name). It also describes the output semantics for each `type`, making the parameter meanings richer than the bare schema definitions.

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 'resolve[s] a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific verbs and examples (ticker, CIK, LEI, RxCUI) and distinguishes itself from siblings by noting it supplies IDs that other tools need. The supported types and their respective outputs are explicitly enumerated.

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 an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also lists example user queries that trigger its use, and mentions it replaces 2-3 manual lookups, clarifying its role in the tool ecosystem. While it doesn't name alternative tools, the condition 'whenever you have a name but need an ID' is a clear, actionable criterion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing that it probes each entity with ai_visibility_check and ranks results, which is useful behavioral context not captured by annotations. It does not contradict annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by the mechanism and use case. Every sentence adds value, with no repetition of schema or annotation details. It is concise and well-structured.

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

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

With no output schema, the description specifies the return format (ranked list with score, confidence, signal density). It also explains the probing mechanism, use case, and example. It is complete for the tool's complexity and provides sufficient context for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal meaning by framing entities as 'your brand + N competitors' and mentioning the ranking output, but it does not significantly enhance parameter understanding beyond the schema. It aligns with the baseline.

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

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

The description clearly states the tool's verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It also distinguishes itself from the sibling ai_visibility_check by focusing on multiple entities and producing a ranked comparison, making it unique among siblings.

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

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

It provides a clear use case: 'competitive AI-marketing audits' with an example question. While it doesn't explicitly state when NOT to use it (e.g., for a single entity, use ai_visibility_check), the context strongly implies it is for multi-entity comparisons. This clear context, without exclusions, aligns with a 4.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses partial-failure behavior, latency (5-30s for first bundlephobia measurement), and the sources_failed field. It also summarizes the return structure, adding meaningful context.

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

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

The description is longer than typical but every sentence contributes: purpose, usage trigger, return contents, ecosystem limitation, and graceful degradation. It is front-loaded with the primary purpose and structured logically.

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 composite tool with no output schema, the description is thorough: it names all return fields, explains the two data sources, covers edge cases (scoped packages, specific versions, timeouts), and gives clear usage triggers. This fully equips 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 already 100% with clear parameter descriptions, so the description adds little new parameter-level meaning. It reinforces NPM-only scope and scoped-package support, but those are already in the schema.

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

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

The description gives a specific verb ('check') and resource ('npm package'), explains the composite nature across deps.dev and bundlephobia, and clearly states the outcome: a should-I-add-this package assessment. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on dependency health and cost.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion for non-NPM ecosystems, directing to deps.dev:version directly, which serves as an alternative.

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 greatly exceeds what annotations provide. It discloses the embedding model (BGE-base-en), similarity mechanism (cosine over 500-char overlapping windows), the 200K character cap with truncation flagging, and the exact return format (passages with offsets and similarity scores). No contradiction with readOnlyHint or other 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 five sentences, each earning its place: purpose, examples, usage, integration, and technical details. It is front-loaded with the core action. Slightly longer than the minimal two-sentence ideal, but every word contributes and there is no redundancy.

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

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

With no output schema, the description fully explains what to expect (top-N passages with offsets and similarity scores). It also covers operational limits (truncation), mechanics (embeddings/windows), and the relationship to sibling tools, making the tool self-contained and complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that 'text' is content already pulled from elsewhere, provides query examples, and explains the 'limit' via 'top-N' and windowing details. This enriches parameter meaning beyond the schema.

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

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

The description opens with a specific verb+resource ('Semantic search INSIDE a fetched record') and names concrete examples (SEC 10-K, article). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and clarifying that it operates on already-fetched text rather than fetching or whole-document grounding.

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 the record is too big to cram into the prompt.' It also outlines a workflow with ask_pipeworx_grounded (fetch first, then ground over relevant passages), providing clear context for choosing this tool over alternatives.

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

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

The description discloses numerous behavioral traits beyond annotations: OAuth account requirement, phone verification, SMS daily cap, webhook signing secret returned once, auto-disabling after 10 consecutive failures, and the always-on feed retrieval path. This far exceeds what the annotations communicate.

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

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

The description is dense but well-structured: core purpose first, then account requirement, supported types with examples, then delivery channels with constraints. Every sentence carries operational weight, and the length is justified by the tool's complexity.

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

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

For a subscription creation tool with 3 parameters and nested delivery objects, the description covers account prerequisites, type-specific parameter schemas, delivery channel mechanics, verification steps, rate limits, webhook security, and retrieval of fired events. It also states the return value, making it highly complete even without an output schema.

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

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

With input schema coverage at 100%, the baseline is 3. The description adds semantic value by explaining specific examples like items:['5.02'] = officer change and clarifying delivery channel details (verified phone, 10/day cap, webhook HMAC signing), which go beyond the schema's syntax.

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

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

The description uses the specific verb 'Create' and identifies the resource as a 'proactive monitoring subscription to a live-data event stream', with a clear return value ('Returns the new subscription id'). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the act of creation.

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

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

It provides solid context: the account requirement, supported subscription types with examples, and delivery channel nuances (feed always on, optional email/SMS/webhook with constraints). However, it does not explicitly direct users to alternative tools for similar tasks, so it falls short of full when-to-use vs. 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: output is category-bucketed, includes tool call shapes, is drawn from a live catalog of thousands of tools, and the behavior of omitting vs. supplying topic. This goes beyond the annotation baseline, though it does not detail the exact return format.

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

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

The description is a single dense paragraph but every sentence carries useful information: example queries, output composition, parameter behavior, and clear usage guidance. It is not overly verbose, though breaking into bullet points could improve scannability slightly.

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

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

Given a single optional parameter, no output schema, and supportive annotations, the description is exceptionally complete. It explains what the tool returns, the categories covered, how to call it (no args vs. topic), and when to use it. There are no significant gaps for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the topic parameter's optional nature and examples, but does not add substantial meaning beyond what the schema already provides (e.g., the schema already lists all allowed values and the omission behavior). No additional semantics are introduced.

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

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

The description clearly states this is an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It uses specific verbs ('returns', 'drawn from live catalog') and differentiates from siblings by emphasizing the 'FIRST' usage and focus on learning what to ask.

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

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

Explicit when-to-use guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter. However, it does not explicitly name alternatives like discover_tools or state when NOT to use this tool, so it falls short of a full 5.

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

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

The description adds valuable behavioral details beyond annotations: the row is deactivated rather than deleted, preserving historical events via recent_alerts. This explains the non-destructive nature and ownership enforcement, which is beyond what annotations indicate.

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

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

The description is concise: three sentences, each conveying essential information without fluff. It front-loads the action and then explains constraints and effects.

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

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

For a single-parameter tool with rich annotations and schema, the description covers the key aspects: what, ownership, and deactivation behavior. No output schema is needed for this simple mutation.

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

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

The schema already fully describes the 'id' parameter as a subscription uuid returned by subscribe, with 100% coverage. The description adds no extra parameter-specific detail, so a 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?

The description clearly states the action ('Cancel a subscription by id') and distinguishes it from siblings by noting ownership enforcement and deactivation semantics. It is specific and unambiguous.

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

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

The description provides clear context for use (canceling subscriptions) and the ownership constraint, but does not explicitly mention alternatives or when not to use. It is still clear enough for an agent to select it appropriately.

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, openWorld, idempotent), the description adds significant behavioral detail: full verdict enumeration, the meaning of could_not_verify (including verification_error{stage,detail} and that it must not be shown as evidence), and the unsupported case. It also reveals internal pipeline routing and efficiency gains, which are not in annotations.

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

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

The description is dense but every sentence earns its place; trigger phrases, routing, verdict semantics, and error handling are all essential. It could be more front-loaded by moving the 'IMPORTANT' caller note earlier, but the current structure flows from use case to behavior to caveats.

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 2-param tool with no output schema, the description is remarkably complete: it states what it returns (verdict, actual value with citation, reasoning), defines all possible verdicts, explains the error state, and describes routing logic. This fully compensates for the missing 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 baseline is 3. The description adds value by explaining tolerance_pct's override behavior and hallucination-detection use case ('set 1–2 for hallucination detection'), and ties claim examples to the financial pipeline. This supplements the schema's parameter descriptions.

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

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

Description opens with concrete trigger phrases ('Is it true that…', 'fact check') and clearly states the verb + resource: natural-language claim verification against authoritative sources. It differentiates from siblings by specifying the two routing paths (SEC EDGAR for financial, grounded pipeline for all else) and notes it replaces 4–6 sequential calls.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes financial vs. general claims routing. However, it does not explicitly name alternative tools or state when not to use, only implied via scope ('unsupported means we looked and cover no source for 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?

The description adds no behavioral context beyond the annotations. It doesn't mention return behavior, idempotency implications (despite idempotentHint=true), or requirements. With annotations already indicating a write operation, the description provides no additional transparency.

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, clear sentence that is easy to parse. It slightly duplicates the title but is efficient and front-loaded. No unnecessary content.

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

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

For a simple two-parameter tool with an output schema, the description covers the basic action but misses context like module-specific required fields, error handling, or idempotency notes. It's minimally sufficient but has 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% with both module and data documented. The description itself does not add parameter details, so the baseline score of 3 applies.

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

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

The description uses a specific verb 'Create' and identifies the resource 'record in Zoho CRM module', clearly differentiating from sibling Zoho tools that get, list, or search records. It directly states the tool's function.

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

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

The description implies usage (when you need to insert a new record into a Zoho CRM module), but it doesn't explicitly state when to use this tool over alternatives, nor does it mention prerequisites like module existence or required fields. It's clear from the name but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is established. The description adds no additional behavioral details such as authentication, error cases, or field selection, but it doesn't contradict annotations. Minimal extra value beyond annotations, so a 3 is appropriate.

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, clear sentence that front-loads the essential purpose. Every word is necessary, and there is no redundancy or filler.

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

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

This is a simple two-parameter read operation with a rich output schema and strong annotations. The description, combined with the schema and annotations, fully covers the tool's purpose, parameters, and safety profile. No significant gaps remain.

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

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

Schema coverage is 100%, with both 'id' and 'module' described in the schema. The description does not add any parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the verb 'get', the resource 'single record by ID', and the context 'Zoho CRM module'. This distinguishes it from sibling tools like zoho_list_records or zoho_search_records, which handle multiple records or different query mechanisms.

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 the use case: when you have a specific record ID and module name. It doesn't explicitly name alternatives or exclusions, but the 'by ID' phrasing makes the intended use clear against the broader list/search siblings. This is clear context without 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?

The description adds no behavioral context beyond the annotations, which already declare the operation as read-only, idempotent, and non-destructive. It does not mention specifics like return format, ordering, or that only module names are returned, offering no incremental transparency.

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 concise sentence, 'List all available modules in Zoho CRM,' with no redundant or extraneous words. It is front-loaded with the action verb and resource, making it easy to parse.

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

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

Given the tool's trivial nature, zero parameters, and the presence of an output schema, the description is sufficiently complete. It conveys the core function without needing additional explanation about return types or behavior, which the output schema likely covers.

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 tool takes zero parameters, so the schema is fully covered and the baseline score is 4. The description does not need to add parameter semantics, and it correctly omits any parameter-related details.

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

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

The description clearly states the tool lists all available modules in Zoho CRM, using a specific verb ('List') and resource ('modules in Zoho CRM'). This distinguishes it from sibling tools like zoho_list_records, which list records instead.

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 no guidance on when to use this tool versus alternatives such as zoho_list_records or zoho_search_records. It only states what it does, leaving the agent to infer usage context from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral traits beyond these annotations; it does not mention pagination, default record counts, or potential large result sets. The only addition is module examples, which are more about purpose than behavior.

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

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

The description is a single, direct sentence that immediately states what the tool does. It is concise, front-loaded, and contains no filler or redundancy. It earns a perfect score for efficiency.

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

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

Given the presence of a full input schema, a read-only annotation set, and an output schema, the minimal description is largely sufficient. It accurately identifies the resource and action. However, it does not explicitly mention that listing is paginated or describe default behavior, which the schema hints at but the description could reinforce for completeness.

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

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

The input schema provides descriptions for all 4 parameters, giving 100% coverage. The description's mention of example modules (Leads, Contacts, Deals) adds slight value by illustrating the 'module' parameter, but it does not enrich understanding of pagination or field selection. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'List' and identifies the resource as 'records from a Zoho CRM module' with concrete examples (Leads, Contacts, Deals). This clearly conveys the tool's function and implicitly differentiates it from siblings like zoho_get_record (single record) and zoho_create_record (creation). However, it does not explicitly contrast with zoho_search_records, so it stops short of full differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for unfiltered listing, nor does it reference zoho_search_records for filtered queries or zoho_get_record for individual records. There is no context for choosing this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no extra behavioral context, such as response format, pagination behavior, or rate limits. It does not contradict the annotations but also provides no value beyond the purpose.

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 sentence of 11 words, extremely concise and front-loaded. Every word is necessary; there is no fluff, repetition, or unnecessary detail.

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

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

Given the strong input schema and annotations, the description is minimally sufficient. However, it does not provide context on when to use this search tool over sibling list tools, which could cause ambiguous tool selection. The output schema exists, so return values are covered, but the missing alternative guidance is a noticeable gap.

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

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

The input schema already provides complete descriptions for all four parameters, including examples, achieving 100% coverage. The description does not add additional semantics beyond the schema, so the 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?

The description clearly states the tool's function: searching records in a Zoho CRM module using criteria. It uses a specific verb ('search') and resource ('records in a Zoho CRM module'), making the purpose understandable. However, it does not explicitly distinguish this tool from the sibling 'zoho_list_records', which may also perform similar operations, so it lacks sibling differentiation.

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

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

The description gives no guidance on when to use this tool versus alternatives like zoho_list_records or zoho_get_record. It does not mention whether this is the appropriate choice for filtered searches or if list_records is better for unfiltered lists. This omission could lead an agent to select the wrong tool.

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