Notion_connect

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: costs (BYO key for Anthropic), default free model, return format (per-model and combined view), and that Anthropic calls are paid directly. No contradictions.

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

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

The description is a single well-structured paragraph (~100 words). It front-loads the main action and output, then covers optional features, return format, and use cases. Every sentence adds value; 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?

Given the tool has 4 parameters (1 required), no output schema, and straightforward behavior, the description is complete. It explains the return format (per-model and combined), how to use optional parameters, and the use cases. No gaps identified.

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 meaning by explaining when to use each parameter: entity is the thing to ask about, models list which models, _apiKey is only needed for Anthropic, context helps disambiguate. This exceeds the baseline.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic integration. The verb 'probe' and resource 'visibility score' are specific and distinguish it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides clear context for when to use the tool: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to pass the _apiKey (for Anthropic model). However, it does not explicitly state when not to use it or compare with alternatives like 'deep_research' or 'entity_profile'.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses significant operational behavior: routes to a massive tool ecosystem, fills arguments automatically, returns structured answers with stable pipeworx:// citations, works on every tier, and is a single fast call. It also implicitly cautions about grounding limitations by directing to ask_pipeworx_grounded for hallucination-resistant answers.

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 dense and well-structured, front-loading the most critical instruction ('PREFER OVER WEB SEARCH') and using concrete examples. It could be slightly tighter, but every sentence contributes useful guidance, covering purpose, usage, alternatives, and citations 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?

With no output schema, the description properly explains the return value ('structured answer with stable pipeworx:// citation URIs'). It also covers routing behavior, fallback alternatives, examples, and even addresses breaking-news scenarios, making it fully complete for a complex, high-traffic entry-point 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 has 100% coverage, documenting the 'question' parameter and all five aliases with clear descriptions. The tool description adds examples and trigger phrases that illustrate what to put in the question, but doesn't fundamentally extend schema-provided parameter semantics, so the baseline 3 applies.

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

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

The description clearly states the tool's role: a router that answers factual questions by selecting from 5,529 tools across 1,455 sources and returns structured answers with citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique purpose immediately clear.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists concrete trigger phrases and examples. It also names alternatives with specific conditions ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part question use deep_research'), giving clear usage boundaries.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable context about its beta nature, the live testing of candidate routing improvements, and the current state (no active candidate, matches ask_pipeworx exactly). This gives the agent a clear understanding of what to expect behaviorally.

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

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

The description is front-loaded with the key fact that this is a beta version of ask_pipeworx, and each sentence adds value. It is slightly wordy with the date and detailed experimental context, but remains efficient and structured well for quick understanding.

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

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

Given the tool's simplicity (one effective parameter) and the existence of a sibling stable tool, the description provides sufficient context for an agent to use it correctly. It explains the relationship to ask_pipeworx, the current state, and how results are used, making it complete enough 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?

The input schema provides 100% coverage of the parameters, all of which are aliases for 'question'. The description mentions 'same arguments' as ask_pipeworx but does not add further semantic meaning beyond what the schema already states. With high schema coverage, 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 identifies the tool as a beta version of ask_pipeworx with the same functionality and scope. It states it is a universal router with identical tools, arguments, and response shape, making its purpose unambiguous. It also distinguishes itself from the stable version by being the experimental edge.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, providing clear usage guidance. It also explains that results are compared against the stable router, implying that the stable version should be used for production or non-experimental needs, though it stops short of an explicit 'when not to use' statement.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the critical behavior of using ONLY tool result content, returning structured success/refusal objects with specific refusal_reason codes, and incurring an extra LLM call. This adds substantial context 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 dense but every sentence earns its place: mode, routing, grounding rule, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the key concept. Slightly verbose but 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 documents return values and refusal reasons. It also explains cost/performance tradeoffs and provides usage context. For a complex meta-tool, this is remarkably 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%—each parameter (including aliases) is documented. The description doesn't add parameter-specific details, but the schema already handles it. Baseline 3 is appropriate since the description provides contextual value but not parameter 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 clearly states the tool's function: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers strictly from tool results, returning evidence and refusals. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded, evidence-based extraction and refusal behavior.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use the tool and when to choose the alternative, satisfying the dimension fully.

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

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

Annotations already declare the tool as safe and read-only. The description adds extensive behavioral context: low-confidence short-circuit, closed-market handling, wide-spread tradeability warnings, cancellation rule parsing, and internal fallback mechanisms for news sources. This goes well beyond annotations.

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

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

The description is very long and detailed, which aids completeness, but could be more concise. It is front-loaded with purpose and examples, but the length may overwhelm an AI agent scanning for quick understanding.

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

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

The description covers virtually every aspect: input handling, classification, fan-out, response shapes, resolver contract, parent event extraction, news backfill, safety behaviors, and resolution rules. No gaps remain given 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?

Even with 100% schema coverage, the description adds value by explaining default behavior for 'depth', recommending 'include_raw': false for typical use, and clarifying the three accepted input formats for 'market'. Schema descriptions alone were already good, but the tool description enhances understanding.

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

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

The description explicitly states the tool researches Polymarket bets by pulling Pipeworx data in one call, with clear verb and resource. It distinguishes from sibling tools focused on other aspects like arbitrage or 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?

Directly specifies use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. This provides clear when-to-use guidance, though sibling differentiation could be more explicit.

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

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

Annotations provide readOnly, openWorld, idempotent hints. Description adds significant behavioral detail: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of pipeworx:// citation URIs. No contradictions.

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

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

Description is front-loaded with example queries, then technical details. It is dense but clear and efficient, with no wasted words. Slight room for better structuring of technical vs. usage info.

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

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

No output schema, but description explains return format (paired data + citation URIs). Covers the complexity of two entity types, data sources, and sorting. Complete for the tool's scope.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: for 'values' it explains tickers for company and names for drug, and constraints like 2-5 items. Enhances schema without repeating.

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 specifies the verb 'compare' and resources 'companies or drugs' with explicit examples like 'X vs Y' and 'head to head'. It distinguishes itself from siblings like entity_profile by stating it replaces sequential single-entity lookups.

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

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

Provides explicit usage preference: 'ALWAYS PREFER over sequential single-pack lookups.' Mentions example queries but does not explicitly state when not to use (e.g., for single entity), though it is implied.

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

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

Discloses many behavioral traits beyond annotations: account/plan requirements, non-open-web operation, parallel tool routing, gaps[] for unanswered facets, contradictions[] for disagreeing findings, hop fields, citation_uri resolvability, semantic excerpting rather than head truncation, and expected latency ranges. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Although long, the description is front-loaded with the most critical info (account required, alternative if not signed in) and every subsequent sentence earns its place by covering a distinct aspect (scope, mechanism, output, use cases, depth variants, citation behavior, excerpting, latency). Dense but not wasteful.

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

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

Despite no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps, contradictions, hop field, and caveats. It also covers account constraints, latency, and how it differs from alternatives. Given the tool's complexity, this is a very complete description.

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 meaningful depth semantics (quick=3 facets, standard=5 with gap recovery + contradictions, thorough=8 with chase leads) and clarifies that questions can be broad/multi-part. This goes beyond the schema's brief enum descriptions, meriting a 4.

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

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

The description clearly states it performs grounded multi-source research across 1455 structured data sources, decomposing questions and routing to tools in parallel. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making the tool's specific role immediately obvious.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking/current-news topics 'prefer ask_pipeworx'. Also notes account requirements and the fallback if not signed in, offering clear decision rules.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' No contradictions.

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

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

The description is a single well-structured paragraph that front-loads the core purpose ('Find tools by describing the data or task.') and efficiently covers usage, return format, and context. No unnecessary words.

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

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

Given no output schema, the description adequately explains the return value ('returns tools with names, descriptions, and full input schemas... ready to call directly'). It also includes default limit information. The tool's complexity (aliases, many domains) is sufficiently covered.

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

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

Schema description coverage is 100%. The description mentions the query parameter and its aliases, but the schema already provides the same information, including examples and alias details. The description adds marginal additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself as a discovery tool to be called first, differentiating from sibling tools that perform targeted tasks.

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

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

Explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use vs. alternatives.

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

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

Annotations already declare the tool safe and idempotent. The description adds behavioral details like fanning out across multiple sources, soft-failing for patents, and not supporting names, enriching the understanding beyond annotations.

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

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

The description is quite long with many example queries; while front-loaded with purpose, some redundancy exists. It could be more concise without losing essential information.

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

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

Given no output schema, the description fairly completely lists returned data sources and fields (filings, fundamentals, patents, news, LEI) and notes on input limitations. It provides sufficient context for understanding what the tool returns.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes further by clarifying that value accepts tickers or zero-padded CIKs, not names, and provides examples, adding meaning beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies. It lists specific example queries and distinguishes from related tools like resolve_entity.

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

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

The description explicitly says to prefer this tool over chaining individual lookups for holistic views, and advises using resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds no extra behavioral context beyond the word 'Delete', which is redundant 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, front-loaded with the purpose, and every sentence adds value. No wasted words.

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

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

For a simple tool with one parameter and comprehensive annotations, the description covers purpose and usage. It could mention irreversibility but the annotations imply it.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description adds no additional meaning beyond the schema.

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

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

The description clearly states the tool deletes a memory by key. It pairs with remember and recall but does not explicitly differentiate from them, though the purpose is 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 scenarios: stale context, task completion, clearing sensitive data. It mentions pairing with remember and recall as alternatives, but does not state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, indicating a safe, non-destructive read operation. The description adds behavioral context (fetches page, extracts title/description/links, emits markdown) without contradicting annotations. No annotation contradiction detected.

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

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

The description is concise with three sentences, no redundancy, and front-loads the primary purpose in the first sentence. Every sentence contributes meaningful information without wasted words.

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

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

The tool has no output schema, but the description explains the output is a 'single text blob ready to drop at site-root/llms.txt', which is sufficient for a simple tool. Combined with strong annotations, the description provides enough context for the agent to understand behavior and output.

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

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

Schema description coverage is 100% with both parameters fully described in the schema. The description repeats the schema info for 'url' and 'max_links' without adding additional semantic context beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers from any URL. It uses specific verbs ('generate', 'fetch', 'extract', 'emit') and specifies the output format ('standard llms.txt markdown format'). It distinguishes from sibling tools by its unique function of file generation for AI indexing.

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

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

The description lists three explicit use cases: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor's AI crawler view. It does not explicitly state when not to use, but the use cases provide clear guidance for selection among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context about return fields and default behavior (active only), which is useful but does not disclose additional traits like auth needs or rate limits.

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

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

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. No redundancy or waste.

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

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

For a simple listing tool with one optional parameter, the description covers purpose, return fields, and usage guidance. No gaps given annotations and schema richness.

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

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

Schema coverage is 100% with parameter description. Description does not add meaning beyond the schema; baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'subscriptions', specifies scope as 'caller's active subscriptions', and lists return fields. It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more' (before subscribe) or 'find an id to cancel' (before unsubscribe). Provides clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds mild context about return content but no additional behavioral traits like error handling or rate limits.

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

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

Single sentence, front-loaded key action, no wasted words.

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

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

With one parameter, rich annotations, and output schema present, the description sufficiently explains the tool's purpose and return content without 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 already documents the only parameter. The description adds no new parameter meaning beyond 'by ID'.

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

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

Describes a specific verb and resource ('Get Notion database schema by ID'), clearly distinguishing it from sibling tools like notion_query_database by focusing on schema, properties, field types, and configuration.

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

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

Implies usage for understanding database structure, but does not explicitly state when to avoid or mention alternatives. Still clear enough given the tool name and context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns 'full properties, metadata, and content structure for reading or editing', which contextualizes the return value. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with no redundant words. Every part serves a purpose, making it efficient for an AI 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?

Given the simplicity of the tool, the description adequately covers its purpose and return content. The presence of an output schema reduces the need to detail return values. Minor gap: could clarify if it works with archived pages, but not critical.

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

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

The single parameter 'page_id' is fully documented in the input schema (100% coverage). The description does not add any extra meaning or usage hints beyond what the schema provides, meeting the baseline.

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

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

The description uses a specific verb ('Get'), identifies the resource ('Notion page'), and clarifies the scope ('by ID'). It contrasts with sibling tools like 'notion_get_database' and 'notion_list_pages', making its distinct role clear.

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

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

The description implies usage for fetching a single page but provides no explicit guidance on when to use or avoid this tool vs alternatives. No when-not or prerequisite information is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying the output (titles and IDs) and scope ('all accessible pages'), which goes beyond annotations. Behavior is clearly safe and non-mutative.

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

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

Single sentence, front-loaded with the core action and outcome. No redundant information; every word earns its place. Appropriate for a simple list tool.

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

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

Given low complexity, full annotations, and existence of output schema, the description adequately covers the tool's purpose and return value. Could mention pagination explicitly, but the schema covers it. Sibling tools are numerous but not described.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add any parameter-specific context beyond what the schema already provides (pagination via page_size and start_cursor). No additional semantics are given.

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

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

Description uses specific verb 'list' and resource 'pages', clearly stating it returns 'titles and IDs to discover available content'. It effectively distinguishes from sibling Notion tools like notion_get_page (single page) or notion_search (search across workspace).

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

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

Description implies usage for initial workspace discovery ('to discover available content') but does not explicitly state when to use versus alternatives like notion_search or notion_query_database. No exclusions or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety profile is clear. Description adds that results include property values, but does not disclose pagination behavior or result limits, which are only in schema. Adequate but not rich.

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

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

Single sentence, front-loaded with key action and resource. No extraneous text. However, could be slightly expanded without losing conciseness to include pagination note.

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?

Has output schema, so return values are covered. Description does not mention pagination or the need for required database_id. For a tool with 5 parameters including nested objects and pagination, the description is minimal but sufficient given schema coverage.

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

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

Schema coverage is 100%, so baseline 3. Description mentions filters and sorting with a simple example but does not add meaning beyond what the schema provides. The example is essentially repeated from the input schema.

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

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

Clearly states it queries a Notion database with filters and sorting, and returns matching rows. Distinguishes from siblings like notion_get_database or notion_get_page by emphasizing structured queries. However, could more precisely differentiate from notion_search.

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 examples but no explicit when-to-use or when-not-to-use guidance. Does not mention alternatives like notion_search for text search or notion_list_pages for simple listing. The context of filters and sorting implies structured queries, but lacking explicit direction.

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 that it returns titles, IDs, and types, which is consistent and provides extra context about the output 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 sentence that is concise and front-loaded with the key purpose. No extraneous information.

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

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

Given the tool has an output schema and annotations covering safety, the description is largely complete. It does not explicitly mention pagination (start_cursor) but that is detailed in the schema. A small gap exists, but overall it is adequate.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description reiterates 'keyword' corresponding to 'query' but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Search your Notion workspace by keyword' and specifies the returned data (titles, IDs, types). It distinguishes itself from sibling tools like notion_get_database (specific database) and notion_get_page (specific page) by emphasizing workspace-wide search.

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 does not provide explicit guidance on when to use this tool versus alternatives such as notion_query_database or notion_list_pages. Usage context is implied but not clarified.

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

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

Annotations are all false, so the description carries the full burden. It discloses the claim_token workflow (anonymous filing returns a token, pass it back to read status/resolution), rate limiting ('5 per identifier per day'), and resources (free, no quota impact, daily digest). It also explains the reporting scope restriction. These go far beyond annotations.

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

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

The description is a single dense paragraph but every clause adds a distinct fact: purpose, use cases, scope exclusion, claim_token flow, rate limit, and cost. It is front-loaded with the primary verb and resource. Though longer than the two-sentence ideal, it efficiently packs necessary context without waste.

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

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

For a feedback tool with four parameters, a nested context object, and no output schema, this description is complete. It explains when to use each feedback type, the claim_token retrieval mechanism (including what the response returns: status and changes), and constraints like rate limiting. No essential behavior is left uncovered.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds behavioral context beyond the schema, especially for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and clarifies it should be used with no other arguments. It also maps feedback types to enum values via usage guidance, adding semantic 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 opens with the exact action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team) and explicitly enumerates the feedback types (bug, feature/data_gap, praise). This distinguishes it from all sibling tools, which are research/Notion operations.

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 precise when-to-use instructions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead', naming the alternative course of action.

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 and idempotentHint. Description adds critical behavioral details: 'Self-aggregating signal — derived from CF analytics-engine, no PII', and 'Cached 5min-1h depending on window', providing transparency beyond annotations.

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

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

Four sentences, front-loaded with the main output, then a numbered list of use cases, ending with data provenance and caching. Every sentence adds value, no fluff.

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

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

With only one optional parameter and no output schema, the description fully explains the tool's purpose, output, data source, privacy, and caching policy. No gaps given the tool's 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?

Schema coverage is 100%, but description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', helping agents choose the window parameter.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume', specifying the verb and resource. It distinguishes itself from siblings through use case differentiation and explaining the self-aggregating signal.

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

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

Explicitly lists three specific use cases (discovering hot data sources, confirming popular tool, checking use case alignment). Does not mention when not to use or compare to alternatives like discover_tools, but context is clear.

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

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

Annotations declare readOnlyHint true, openWorldHint true, idempotentHint true, destructiveHint false, which the description does not contradict. The description adds important behavioral details such as fill checking against CLOB depth, realizable edge vs theoretical, partition filtering, and semantic anchor for cross-event pairs. This goes beyond annotations but could benefit from more structured 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 dense with information and well-structured, starting with purpose then detailing modes. It is somewhat lengthy but every sentence adds value. Minor redundancy in explaining modes could be tightened.

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

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

Given no output schema, the description explains the response structure (opportunities array, partition_check details, fill check metadata). It covers key edge cases like low similarity filtering and placeholder filtering. For a complex tool, it provides sufficient context for understanding outputs and behavior.

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

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

Schema description coverage is 100% with both event and topic parameters described. The description adds value by specifying that event accepts slug or full URL and topic accepts seed questions, and clarifies how each mode behaves. This supplements the schema meaningfully.

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 specifically states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection across multiple modes.

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

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

The description explains three usage modes: no args for trending scan, event for specific market, topic for cross-event scan. It recommends event mode and explains the advantage of cross-event mode. However, it does not explicitly state when not to use this tool or provide alternatives for cases not covered.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint true, and destructiveHint false. The description adds significant behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment with diagnostics), edge calculation details, and exclusions (Fed bets). 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 well-structured with clear section headers and bullet points, but it is lengthy (several paragraphs). Every sentence adds detail, though some operational specifics (e.g., historical alpha values per sport) could be summarized more concisely for quick agent parsing.

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

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

Given the complexity (9 optional parameters, no output schema, multiple sibling tools), the description is thorough. It explains output segments, diagnostics, caching, edge calculation, and specific filtering rules. The absence of an output schema is compensated by detailed textual description of the response structure.

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 detailed parameter descriptions. The description adds value by explaining how parameters interact (e.g., tradeable-edge knobs group min_liquidity and max_spread_pp, min_partition_leg_kelly's role in partition filtering). This contextual grouping enhances understanding beyond the schema.

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

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

The description uses specific verbs ('scan', 'return opportunities') and clearly states the tool's purpose: identifying Polymarket markets where Pipeworx data disagrees with market price. It explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven edge detection rather than pure arbitrage or time-series tracking.

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 ('what should I bet on today') and includes guidance on adjusting knobs (min_liquidity, max_spread_pp). However, it does not explicitly state when to avoid this tool in favor of alternatives, such as polymarket_edge_tracker for historical tracking or polymarket_arbitrage for pure arbitrage.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral detail: output structure, snapshot gaps meaning, decay computation method (daily closes, not intraday), and history bounds. 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?

Moderately long but every sentence adds value. Information is front-loaded with the key question. Could be slightly trimmed, but overall efficient for the complexity.

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

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

Given no output schema, the description thoroughly covers tracked, expired, and snapshot_dates fields, their meanings, and LIMITS. For a 2-param tool with full schema coverage, this is exceptionally 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%. Description adds default values (days=14, window='1wk') and explains days as lookback and window as snapshot family. Goes beyond the schema by clarifying clamping and default behavior.

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

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

Clearly states it answers 'how long has this edge existed and is it shrinking?' and distinguishes a fresh wide edge from an old one. The purpose is specific and distinct from related sibling tools like 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?

Provides clear context on when to use (for edge persistence/decay telemetry) and details what the response contains. Lacks explicit 'when not to use' or direct alternatives, but the LIMITS section adds useful constraints.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the risk of partial fills and forced directional risk, which are beyond the annotation information. 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 quite long and contains some redundancy (e.g., repeated explanation of modes). While well-structured with sections, it could be more concise. Some sentences are dense and could be streamlined.

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

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

Despite no output schema, the description lists all return fields for both modes, explains risks, and describes forced directional risk. This is highly complete given the tool's complexity and the absence of an output schema.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema. It explains the two modes, the default logic for side in basket mode, and the interpretation of size_usd for buys vs sells and for baskets. This is valuable additional context.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order book depth. It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on signals.

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 that partial basket fills convert an arb into an unhedged directional position, which is crucial context for when to use the tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: compatibility_warning conditions, temporal alignment, skipped counters, and the rarity of real spreads. 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 longer but well-structured, front-loaded with purpose and modes, then detailing response and safety fields. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

No output schema exists, but the description compensates by thoroughly explaining the response structure, safety fields, compatibility warnings, temporal alignment, and skip counters. For a complex tool, it is remarkably complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description further explains the topic shortcuts list, the explicit mode overrides, and provides usage examples. This adds meaning beyond the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic and explicit) and defines the output. It differentiates from siblings like polymarket_arbitrage by focusing on this specific cross-venue comparison.

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

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

The description explicitly tells when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility_warning and are not tradeable. It explains conditions where no arb exists (incompatible bet shapes), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint as safe operations. The description adds valuable context: scoping ('anonymous IP, BYO key hash, or account ID') and pairing with remember/forget, which goes beyond the annotations and helps the agent understand 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 concise (3 sentences) and front-loaded with the main action. Every sentence adds value: retrieval behavior, use case, scoping, and pairing. No wasted words, but could be slightly more structured.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers the core behavior (retrieve vs. list), scoping, and pairing with sibling tools. It is complete for an agent to understand how and when to use recall.

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 one optional parameter 'key' described clearly. The description echoes the schema ('omit key to list all'). It adds an example ('user_research_topic') but little extra meaning 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's purpose: 'Retrieve a value previously saved via remember, or list all saved keys'. The verb is specific (retrieve/list), the resource is explicit (memories), and it distinguishes between two modes of use. No confusion with sibling tools like remember or forget.

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

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

The description provides use case examples: 'the user's target ticker, an address, prior research notes' and notes scoping ('Scoped to your identifier'). It implies when to use (look up stored context) but does not explicitly state when not to use or compare to alternatives beyond pairing with remember/forget.

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 no destructive hint. The description adds that mark_read flags events read and influences future calls, that polls are safe, and provides the alternative HTTP endpoint—valuable behavioral context beyond the annotations.

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

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

The description is a single paragraph that front-loads the main purpose and then efficiently covers parameter details and usage notes. Every sentence adds value with no redundancy, though it could be slightly more 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 explains return fields (source, citation_uri, raw payload). It covers all 5 parameters and addresses polling behavior. The only minor gap is not mentioning pagination or ordering, but overall it's fairly complete for a list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: it explains mark_read as 'flag returned events read so the next call only shows newer ones,' gives an example for type ('sec_8k'), and clarifies since as ISO timestamp. This extra context justifies a 4.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies what each event carries (source, citation_uri, raw payload) and distinguishes itself from siblings like list_subscriptions by focusing on alert events.

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

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

The description states 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This provides context on when to use the tool vs. the HTTP endpoint, but it does not explicitly compare to sibling tools like recent_changes.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the fan-out behavior, GDELT→GNews fallback, USPTO soft-fail condition, and output structure (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads the purpose with real-world query examples, then efficiently covers sources, parameters, and output. Every sentence provides value, though it could be slightly restructured for skimmability.

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 mentions the return structure (changes[], total_changes, citation URIs). Parameter details are sufficient. For a multi-source tool with fallback logic, the description covers key aspects without 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% (baseline 3). The description adds meaningful context: explains 'since' format with examples (ISO date and relative shorthand), acceptable values for 'type' (only company), and 'value' options (ticker or CIK). This enriches the schema's basic descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a time window, enumerates data sources (SEC EDGAR, GDELT, GNews, USPTO), and explicitly differentiates from sibling tool entity_profile by noting when to use each.

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

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

The description includes example queries and explicit guidance to prefer entity_profile for static profiles. It also recommends typical 'since' values like '30d' or '1m'. While it doesn't list exhaustive when-not-to-use scenarios, the context is clear.

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

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

Discloses persistence details (scoped by identifier, 24-hour retention for anonymous sessions, persistent for authenticated users) beyond annotations, which already indicate idempotent and non-destructive behavior. 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 concise and well-structured: first sentence states the main action, followed by usage guidance, then persistence details, and finally sibling references. Every sentence serves a purpose.

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

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

Given the simple tool (2 required string params, no output schema), the description fully covers its purpose, when to use, storage semantics, and integration with siblings, leaving no gaps for an agent to misuse it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing naming conventions for the key (e.g., 'subject_property') and clarifying the value as any text, which enhances understanding.

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

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

The description clearly states the tool saves data for reuse across conversations, specifies the verb 'Save data' and the resource 'key-value pair', and distinguishes it from siblings like recall and forget.

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

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

Explicitly provides when to use ('when you discover something worth carrying forward') and how it pairs with siblings ('Pair with recall to retrieve later, forget to delete'), offering clear context and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable detail: internal cascading across multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields instead of omission, and source labeling for each identifier. This exceeds what annotations provide.

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

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

The description is long but every sentence contributes substantive information about behavior, supported types, and fallback handling. It is front-loaded with examples and a clear purpose. However, the length is slightly heavy, so it doesn't achieve top marks 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?

Despite lacking an output schema, the description explains return contents, identifier sources, unresolved handling, and applicable scenarios for both entity types. It provides a comprehensive understanding of tool behavior for a complex multi-endpoint lookup, making it effectively 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% and already describes the parameters clearly. The description enriches this by specifying accepted input forms (ticker, CIK, name) and detailed output semantics (CIK, ticker, LEI, FIGI, RxCUI) for each type, adding meaning beyond the bare schema descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples of queries and supported types. It distinguishes itself from siblings by noting that other tools require these identifiers as input, positioning it as a foundational lookup tool.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing a clear condition for use. It also explains that it replaces 2-3 manual lookups, but does not explicitly mention alternative tools or when NOT to use it, so it stops short of a perfect 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?

Adds behavioral detail about probing, ranking, and output format. Annotations already convey read-only, idempotent, non-destructive nature; description aligns and adds value.

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 front-loaded sentences: first describes action and method, second provides usage scenario and output details. No redundancy.

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

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

Covers purpose, method, output format, and usage scenario. Could mention it makes multiple calls to ai_visibility_check, but implicit. Satisfactory completeness.

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

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

Schema covers all 4 parameters with descriptions. Description adds semantic context: first entity treated as 'subject' for narrative, _apiKey required only for anthropic model.

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

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

Description clearly states tool compares AI visibility across multiple entities using ai_visibility_check probes, then ranks results. Differentiates from single-entity probe ai_visibility_check and general comparison 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?

Provides usage context for competitive AI audits and example question, implying multi-entity comparison. Does not explicitly state when not to use or name alternatives, but context makes it clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds key behavioral details: fans out across multiple services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list it if it times out. 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 multi-sentence but every sentence adds value. It front-loads the purpose and use case, then details the return fields and edge cases. No fluff or redundancies.

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 (composite check, no output schema), the description is remarkably complete. It lists the summary block fields, per-advisory details, links, and alternative versions. It also explains partial failure behavior and timing, leaving the agent well-informed about what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds marginal value by reiterating that version defaults to latest when omitted and that scoped packages are accepted. This is helpful but largely duplicates the schema. Still, it confirms understanding.

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

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

The description clearly states the tool is a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the use case: answering if a package is safe, popular, or small. The title 'Scan Dependency' aligns well. No sibling tool has similar functionality, so it's distinctive.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing concrete examples. It also states 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', indicating when not to use this tool.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behaviors: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K character cap with truncation and flagging. It also describes the return format (passages with offsets and similarity scores), providing full 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 concise yet comprehensive. It uses bold for key terms, is front-loaded with the purpose, and every sentence adds value (usage scenario, pairing, technical details, limitations). No redundant or vague statements.

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

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

Given no output schema, the description adequately covers return values (passages with offsets and scores). It explains the algorithm, truncation, and pairing with another tool. For a tool with moderate complexity, this completeness is sufficient.

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

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

Though schema coverage is 100%, the description adds significant context: text is 'already fetched', query is natural language, limit is top-N passages. It explains the truncation behavior for text and the typical use case, enhancing understanding beyond the 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 that this tool performs semantic search inside a previously fetched record, returning passages with offsets and scores. It distinguishes itself by explicitly contrasting with using the whole record in the prompt, and mentions pairing with ask_pipeworx_grounded, which differentiates it from sibling tools like ask_pipeworx.

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

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

The description gives explicit guidance: use when the record is too large for the prompt, and pairs with ask_pipeworx_grounded for grounding. It explains that it saves context and returns only relevant passages, helping agents decide when to use this tool instead of 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?

Beyond annotations, the description adds behavioral details: requires OAuth account, returns new subscription ID, delivery limits (10/day for SMS), and auto-disable for webhooks. 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 well-structured and efficiently packs purpose, requirements, types, and delivery options into a few sentences. Slightly long but justified by complexity.

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

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

Given the tool's complexity (nested objects, multiple types) and no output schema, the description covers purpose, prerequisites, type examples, delivery details, and return value. Missing some post-subscription steps but adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with concrete examples for each type and extra details on delivery channels (e.g., webhook signing), improving parameter understanding.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream', which clearly states the verb (create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies a prerequisite (Pipeworx OAuth account) and explains supported types and delivery channels, guiding when to use the tool. However, it does not explicitly state when not to use it or list alternatives for other operations.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds value by detailing return content and default behavior, but does not cover potential limitations like rate limits.

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

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

The description is concise but front-loaded with key terms; it packs substantial information into a single paragraph without being 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?

Despite no output schema, the description adequately explains the return value (category-bucketed examples with tool details), covers multiple invocation patterns, and addresses the target audience.

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

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

Schema coverage is 100% with parameter description. The description enriches by listing specific topic values (finance, pharma, etc.) and explaining how omission changes behavior.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and positions it as an onboarding entry point for new users.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic vs. omit it, providing clear 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?

Discloses that the row is deactivated not deleted and that historical events remain via recent_alerts. Adds value beyond annotations, which already indicate non-destructive and idempotent 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?

Two sentences, front-loaded with action, no unnecessary words. Efficient and focused.

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

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

For a simple tool with one parameter and no output schema, the description, combined with annotations, provides complete context. Includes ownership, behavioral nuance, and cross-reference to recent_alerts.

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

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

Schema coverage is 100%, and the description includes 'Subscription id (uuid) returned by subscribe,' which mirrors the schema. No additional semantic context provided beyond what is 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 clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. Does not explicitly mention when not to use, but the condition is well-defined.

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/idempotent annotations by disclosing the meaning of 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence) and distinguishing it from 'unsupported' (no source found). This is critical behavioral nuance not present in any structured field.

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 longer than typical descriptions, every sentence adds value: trigger phrases, usage guidance, routing logic, verdict taxonomy, error semantics, and efficiency benefit. It is front-loaded with the core purpose and examples, and the special-case explanations are succinctly packed.

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

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

For a tool with no output schema, the description adequately covers return values (verdicts, actual value, citation, reasoning), error conditions, routing decisions, and performance advantages. It gives enough detail for an agent to understand the tool's full behavior and limitations.

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

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

Schema already covers both parameters 100%, but the description adds valuable context: tolerance_pct's default behavior (implied by wording, capped at 5) and its override semantics for hallucination detection. It also gives concrete claim examples that clarify expected input format beyond the schema.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It includes specific trigger phrases ('fact check', 'verify the claim that') and distinguishes between company-financial claims and any other factual claim, making its scope unmistakable. It also differentiates itself from broader research tools by focusing on true/false verdicts.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing behavior (SEC EDGAR fast path for financial claims, grounded pipeline for everything else) and notes that it replaces 4–6 sequential calls, giving clear context for when to invoke it over alternatives.

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