Webflow

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds context about return format (per-model {score, confidence, signals, raw_response} + combined view) and that Anthropic requires a BYO API key, which are valuable beyond annotations.

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

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

Three sentences covering core action, model options, return format, and use cases. No wasted words, front-loaded with the primary 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?

Despite no output schema, the description sufficiently explains return values, parameters, and pricing model. Covers all necessary context for a tool with 4 well-documented parameters and good annotations.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining the default model, the role of _apiKey, and providing examples for the entity parameter, though not all parameters gain additional meaning.

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

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

The description clearly states it probes LLMs to score visibility (0-100) per model, with specific verbs and resource. It distinguishes from siblings by its unique focus on AI visibility scoring, though not explicit about siblings.

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

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

Lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use free vs paid models. Does not explicitly mention when not to use or alternative tools.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context: internal routing across thousands of tools, argument filling, structured answers with stable citation URIs, and that it works on every tier in one fast call. Minor gap: no detail on rate limits or latency, but annotations carry the safety burden.

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

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

The description is longer than typical but every section earns its place: preference rule, scope, trigger phrases, examples, escalation path, and sibling differentiation. It is front-loaded with the most important instruction and uses bullet-like sentences effectively, though examples could be trimmed slightly.

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

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

For a question-routing tool with no output schema, the description fully explains what an agent needs: when to use it, what it does internally, what kind of answer to expect (structured with citation URIs), and when to choose a sibling tool. Nothing critical is missing.

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

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

Schema description coverage is 100% and the schema already documents the parameter aliases. The description reinforces natural-language input but does not add significant meaning beyond what the schema provides. This matches the baseline for fully covered schema parameters.

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 a specific verb ('routes') and resource (5,706 tools across 1,493 verified sources), and explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research. It leaves no ambiguity about what this tool does or how it differs from neighboring tools.

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

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

The description is explicit about when to prefer this tool over web search, lists trigger phrases and concrete examples, and states exactly when to escalate to ask_pipeworx_grounded or deep_research. This is model-prompt-grade usage guidance.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the live-candidate routing behavior, the current no-active-candidate state with a retirement date, the comparison process against the stable router, and the explicit 'falls back to nothing' assurance that it is a full working router. This is exactly the kind of behavioral nuance an agent needs when dealing with a beta variant.

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 identity and experimental status, and each sentence contributes a distinct piece of context. There is minor redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but the overall size is reasonable for the amount of caveat it must communicate.

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 experimental status, current parity with stable, usage instruction, and the no-fallback guarantee. With no output schema, it references 'same response shape' rather than spelling out the response contract; this is sufficient given ask_pipeworx is a sibling tool, but not fully self-contained.

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

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

The input schema already documents all six parameters, including the six aliases for the single required question parameter, so schema coverage is 100%. The description only says 'same arguments' and adds no parameter-level detail; at this coverage, 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 identifies the tool as a beta version of ask_pipeworx with the same scope (5,706 tools), arguments, and response shape, and distinguishes it from the stable sibling by labeling it the experimental edge. It stops short of a fully literal statement like 'routes natural-language questions to one of 5,706 tools,' but the router role is clear enough for an agent.

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

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

It explicitly says to use the tool 'when you want the newest routing' and explains current parity with ask_pipeworx, plus the comparison-to-stable-router workflow. It stops short of an explicit 'when not to use this, use ask_pipeworx instead' statement, so it is clear context but not a full when/when-not exclusion guide.

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

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

The description goes far beyond the annotations by detailing the exact success/refusal return shapes, enumerating possible refusal reasons, and stating that the answer uses 'ONLY what the tool result contains.' It also mentions the extra LLM call cost, providing rich behavioral context consistent with the readOnly/openWorld/idempotent annotations.

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

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

Every sentence earns its place: the first sentence states the mode, the second explains the routing and extraction pipeline, the third gives return/refusal shapes, the fourth defines the use case, and the fifth gives the cost comparison. It is dense but efficient, and the key differentiator is front-loaded.

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

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

Despite having no output schema, the description fully compensates by specifying the success return fields and all refusal reasons. It also covers when to use, when not to use, and the cost implication, providing everything an agent needs to invoke and interpret this tool correctly.

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

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

The input schema already covers all six parameters with 100% description coverage, with explicit alias documentation. The description adds no parameter-level meaning beyond 'question in natural language,' which is already stated in 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 states a specific verb and resource: it 'EXTRACTS the answer using ONLY what the tool result contains' in 'hallucination-resistant answer mode.' It also clearly distinguishes itself from ask_pipeworx by explaining it uses the same routing but adds grounded extraction and explicit 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?

The description explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives the alternative: 'prefer ask_pipeworx for casual lookups' and names the cost trade-off ('costs one extra LLM call').

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 significant behavioral context: low-confidence match short-circuit, closed market handling, wide spread warnings, cancellation rule risk, and details on response inspection. 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 very long and covers many edge cases. It is structured with capitalized section headers, which helps readability, but it is not concise. Some sentences could be trimmed 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 the tool's complexity (3 parameters, no output schema), the description is exceptionally thorough. It covers market resolution, classification, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback, safety, wide spreads, and cancellation rules. It leaves no major gaps.

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

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

Schema coverage is 100%, with each parameter having a clear description. The overall description does not add meaning beyond the schema for parameters, 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 starts with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then adds specific use cases and differentiates from siblings by focusing on Polymarket and Pipeworx, which are not mentioned in sibling tool names.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive context on the tool's behavior and outputs, though it does not explicitly list when not to use it or name 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 (readOnly, openWorld, idempotent), the description reveals key behaviors: company data comes from LATEST 10-K via SEC EDGAR/XBRL, off-calendar fiscal years handled correctly, results sorted by primary metric, and returns paired data with citation URIs. This exceeds annotation coverage.

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: begins with usage examples, then key advice, then data sources per type, then output details. It is somewhat lengthy but each sentence adds value. Could trim minor redundancy but overall efficient.

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

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

Given no output schema, the description adequately describes return format (paired data + citation URIs) and behavior (sorted results). It covers both entity types thoroughly, including data sources and fiscal year handling. No gaps remain for an agent to understand what the tool does and 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 adds value by elaborating on the 'values' parameter: for company it specifies tickers/CIKs, for drug names, and mentions max 5 and min 2. It also explains how results are sorted, which is not 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 it performs side-by-side comparison of 2-5 companies or drugs, with specific invocation examples like 'X vs Y' and 'rank these companies'. It distinguishes from siblings like entity_profile (single entity) and search_within by emphasizing efficiency over sequential lookups.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', which strongly guides when to use. However, it does not explicitly mention when not to use (e.g., for single entity lookups), though that is implied by the comparison focus.

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

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

The annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context: account/paid-plan requirements, gap[] honesty (never invented), stable citation_uri only when resolvable, contradictions[] for standard/thorough, semantic excerpting, and 15-60s/90s timing. No contradiction with annotations.

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

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

The description is long, but nearly every clause carries operational information (auth, alternatives, output packet, depth semantics, latency). It is front-loaded with the most critical constraints (account required, use ask_pipeworx instead) before the mechanism. It could be tightened, but the density is justified for a complex tool.

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

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

Despite having no output schema, the description fully explains the return shape (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field) and the practical fallback behavior for uncovered topics. Combined with rich annotations and complete parameter docs, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3; the description earns a 4 by adding non-obvious behavioral meaning: depth:'thorough' requires a paid plan, standard/thorough trigger a gap-recovery/contradiction pass, and latency expectations vary by depth. It does not merely restate the schema.

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

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

Opens with a clear verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources...' and distinguishes itself from siblings ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'). It states the best-use cases with concrete examples, so an agent can tell deep_research apart from ask_pipeworx and other research tools.

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

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

Gives explicit when-to-use and when-not-to-use conditions: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, prefer ask_pipeworx for breaking/current-news topics, and use ask_pipeworx if not signed in. It even covers depth tiers and expected latency, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by explaining that 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 second schema lookup needed.' This adds valuable behavioral context about the return format and readiness for invocation, which annotations do not cover.

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

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

The description is front-loaded with the purpose and usage context. The list of domains is somewhat verbose but adds helpful specificity. Each sentence contributes value (purpose, when to use, what returns). It could be slightly more concise but is well-structured and informative.

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

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

No output schema exists, but the description explains the return structure (names, descriptions, full schemas). The parameter count is 6 (many aliases), and the description covers the key 'query' parameter with examples and alias listing. For a discovery tool with 100% schema coverage and annotations, this is adequately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases (task, q, description, search) and provides examples, but the schema already documents these with similar detail. The description does not add significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings by positioning it as the first call for tool discovery ('Call this FIRST when you have many tools available'). This contrasts with siblings like deep_research or search_within, which focus on data retrieval rather than tool discovery.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context on when to invoke it and when not to (e.g., when you already know the tool or want a single answer).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, no destruction. The description adds significant behavioral context: fans out across multiple sources (SEC, USPTO, news, etc.), notes USPTO API sunset, soft-fail behavior, and output structure. 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 but front-loaded with use cases. It's appropriately sized for the tool's complexity, though some structure (like bullet lists) could improve readability. Every sentence provides 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 the tool has 2 required params, no output schema, and complex multi-source behavior, the description covers inputs, sources, and output fields adequately. It also notes caveats (USPTO sunset). Agents can decide usage without confusion.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema: explains type is only 'company', value can be ticker or CIK, and explicitly warns names are not supported. This adds value for the agent.

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 like 'tell me about X', 'research', 'brief me', and clearly states the tool provides a full cross-source profile of a US public company. It distinguishes from siblings by explicitly preferring this over chaining individual lookups.

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

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

Explicitly states to prefer this tool over chaining single-pack lookups when a holistic view is needed. Also warns that names are not supported and directs to use resolve_entity first, providing clear when-to-use and alternative 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, so the destructive nature is known. The description confirms deletion but adds no further behavioral details like reversibility or side effects. It provides usage context but not 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 concise, with two short sentences. The first sentence states the purpose, and the second provides usage guidance and related tools. 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?

For a simple tool with one parameter and no output schema, the description covers the core action, usage context, and relationship to siblings. It lacks details on return values or errors, but these are often implicit or handled elsewhere.

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 only one parameter 'key' described as 'Memory key to delete'. The description adds no additional semantic information 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 the verb 'Delete' with the resource 'memory by key', clearly stating the tool's action. It distinguishes from siblings by referencing 'remember' and 'recall', indicating these are complementary tools.

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

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

The description explicitly provides usage scenarios: when context is stale, task is done, or to clear sensitive data. It does not mention when not to use or list alternatives, but the context is clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and outputs standard markdown. It does not disclose rate limits or auth needs, but given the strong annotation coverage, this is sufficient.

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

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

The description is concise: two sentences plus a use-case list, with no fluff. Key information is front-loaded, and every sentence adds value.

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

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

For a simple tool with 2 parameters, the description explains the process (fetch, extract, emit) and output format. No output schema exists, but the description compensates. Slightly more detail on edge cases or error handling could help, but overall complete.

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

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

Schema description coverage is 100%, so both parameters are well-documented in the input schema. The description adds minimal new meaning beyond explaining the output format. A baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating an llms.txt file for any URL. It specifies the verb (generate), resource (llms.txt), and scope (any URL), making it distinct from sibling tools like ai_visibility_check or 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 explicit use cases (client indexing, own project, competitor audit), offering clear guidance on when to use. However, it does not mention when not to use or explicitly differentiate from similar tools, leaving room for improvement.

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, so the description is not required to repeat those. It adds value by describing the return structure (draft/archived status, fieldData), which provides behavioral context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with the action and resource, minimal waste. Every sentence adds value, including the usage hint and return field list.

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 (2 required params, no nested objects, no output schema), the description covers purpose, usage, and return fields adequately. Annotations handle the safety profile. No gaps for a read-only retrieval tool.

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

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

Schema coverage is 100%, with each parameter having a description. The description enhances this by connecting the parameter origin (e.g., item_id from list_collection_items, collection_id from list_collections), adding contextual 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 gets a single item from a Webflow CMS collection by ID, and specifies the returned fields (id, draft/archived status, last published time, fieldData). It distinguishes itself from list_collection_items, making its purpose unambiguous.

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

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

States 'Use after list_collection_items to read one piece of Webflow site content in detail,' giving explicit context for when to invoke. While it doesn't explicitly list alternatives, the usage guidance is clear and the sibling list includes the relevant listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is clear. The description adds value by listing the specific metadata fields returned, enhancing transparency beyond annotations.

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

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

Two sentences, no wasted words, front-loaded with action and resource. Efficient and clear.

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

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

For a simple read tool with one parameter and no output schema, the description is fully adequate: explains what it does, what it returns, and when to use 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 covers 100% of the single parameter (site_id) with description. The description reinforces that it comes from list_sites, adding minor context, but does not substantially increase 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 'Get metadata for a single Webflow site by its id' and lists specific fields (display name, short name, etc.), making the purpose unambiguous and distinct from siblings.

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

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

Explicitly says 'Use after list_sites to inspect a specific site before browsing its CMS collections and content,' providing clear when-to-use and sequential context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining the return structure (paginated items with id, status, timestamps, fieldData) and pagination behavior, which goes beyond annotations.

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

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

Two sentences that front-load the core purpose with examples, no wasted words. Efficient and clear.

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 list operation with three well-documented parameters and no output schema, the description adequately covers the return structure and pagination. Lacks mention of error handling or rate limits but is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning to parameters beyond what the schema provides; it mentions collection_id implicitly but no extra detail.

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

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

The description clearly states the tool lists items in a Webflow CMS collection, providing examples like blog posts and products. It distinguishes itself from siblings such as get_collection_item and list_collections by specifying it returns live site content.

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 to read the actual content stored in a Webflow collection,' setting clear context for when to use. It does not mention alternatives or when not to use, but the context is sufficient for a read-only 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, idempotentHint, etc., so description adds limited behavioral info beyond listing return fields. No contradictions, but extra context is minimal.

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, then return fields, then usage guidance. Every sentence earns its place; no wasted words.

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

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

Given one parameter, full schema coverage, good annotations, and no output schema needed, the description provides complete guidance 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%, and description adds valuable context: site_id comes from list_sites. This helps the agent understand how to obtain the parameter value.

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

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

Description starts with clear verb+resource: 'List the CMS collections defined on a Webflow site.' It specifies return fields (id, display name, slug, etc.) and distinguishes from sibling tools like list_collection_items and get_collection_item.

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

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

Explicitly states when to use: 'to discover the CMS structure of a site before listing or reading collection items.' Provides clear context but could be more explicit about when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by specifying exactly what fields are returned (id, display name, short name, preview URL, last published time, custom domains). No contradictions.

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

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

Two sentences, front-loaded with purpose, no wasted words. Every sentence is informative and earns its place.

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

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

Low complexity tool with no parameters and no output schema. Description fully explains the return fields and intended use. No missing information for an agent to select and invoke correctly.

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

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

No parameters are defined; schema coverage is trivially 100%. With zero parameters, baseline is 4. Description does not need to add further parameter information.

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

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

Description clearly states 'List all Webflow sites accessible to the connected account' using a specific verb and resource. It distinguishes from siblings like 'get_site' (single site) and 'list_collections' (collections of a site) by focusing on discovery.

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 using this tool 'to discover which Webflow sites are available before reading their CMS collections or site content.' This provides clear context, though it does not explicitly list when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds details on return fields and purpose, which is useful but not essential given the annotations. No behavioral 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 two sentences, front-loading the core action and immediately listing return fields. Every sentence serves a purpose with no redundancy. Highly concise and well-structured.

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

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

For a simple list tool with good annotations and a single parameter, the description covers the purpose, return fields, and usage context. No output schema exists, but the return fields are listed. It could mention filtering behavior (e.g., only active by default), but the parameter cover inactivity. Overall complete enough.

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 has one optional boolean parameter with a complete description in the schema itself. The tool description does not add any additional meaning or usage hints for the parameter. Schema coverage is 100%, 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 'List the caller's active subscriptions' with a specific verb and resource. It also lists return fields, making the purpose unambiguous. While it doesn't explicitly differentiate from other list tools, the resource 'subscriptions' is distinct from siblings like list_collections or list_sites.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies using before subscribe or unsubscribe. It doesn't mention when not to use, but the guidance is actionable.

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

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

The description discloses far more than the annotations do: it mentions rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for anonymous users, the fact that it's free and doesn't count against tool-call quota, and that the team reads digests daily. These are meaningful behavioral insights that go beyond the minimal annotation flags, and there is no contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the purpose, then systematically covers use cases, exclusions, token flow, rate limits, and cost. No filler or repetition; it is appropriately sized for a tool with nuanced behavior.

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

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

For a feedback tool with no output schema, the description fully covers the key contextual aspects: how to frame feedback, who it applies to, what anonymous users can expect (claim_token), how to follow up, rate limits, and quota impact. The schema provides the parameter details, and the description fills in the behavioral and workflow gaps completely.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explaining the claim_token round-trip usage. While it doesn't cover all parameters in prose, the schema already documents type and context well, so this extra guidance elevates it.

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

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

The description opens with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately conveys the verb (tell/feedback) and resource (Pipeworx team) and distinguishes itself from sibling tools like ask_pipeworx by emphasizing it is exclusively for feedback about Pipeworx tools served by this connection.

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

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

Explicit when-to-use guidance is given with concrete examples: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear when-not-to-use by stating it only applies to tools on this Pipeworx connection and not other vendors' MCP servers, directing users to file elsewhere.

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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: data source (CF analytics-engine), no PII, caching duration (5min-1h), and aggregated nature. 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 a clear first sentence, bulleted use cases, and additional details. It is information-dense but not overly long; each sentence earns its place.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, behavior, and parameter semantics completely. It explains what is returned (top tools, top packs, total call volume) and caching, so agents have full context.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by explaining the effect of each enum choice: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's description.

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

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

The description clearly states the verb 'Returns' and the resource 'top tools, top packs, and total call volume over a recent window'. It distinguishes from siblings like 'discover_tools' by emphasizing trending based on other agents' calls.

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

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

The description provides a 'Useful for' section with three specific scenarios, giving clear context for when to use the tool. It does not explicitly name alternatives or state when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral details: the monotonicity violation logic, partition checks, Jaccard similarity threshold (0.30), placeholder filtering (>20% yields null), fill check using CLOB depth, and conditions under which realizable edge is zero (do not trade). No contradictions with annotations.

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

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

The description is well-structured: starts with a high-level summary, then details each mode, then explains additional filters and response structure. It is front-loaded with purpose. However, it is somewhat verbose, especially the fill check paragraph, though every sentence adds value. Could be slightly more concise without losing clarity.

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

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

Given no output schema, the description compensates by explaining the response format (opportunities[] with fields, partition_check object in event mode) and edge cases (low similarity, placeholder filtering, fill check). It does not document error conditions or rate limits, but overall it is highly complete for a complex tool with multiple modes.

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 significant value by explaining what each parameter does in detail: 'event' walks child markets and checks date/threshold ordering plus partition sum; 'topic' searches related events and flattens markets. It provides examples of valid values (slugs, URLs, seed questions) and explains internal logic like semantic anchor and partition filter.

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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges by its specific purpose. The verb 'find arbitrage opportunities' combined with the specific methods makes the purpose unambiguous.

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

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

The description explicitly explains when to use each mode: no args for trending scan, 'event' for single-event partition check, and 'topic' for cross-event scanning. It recommends 'event' for specific markets and explains when cross-event mode catches patterns that single-event misses. However, it does not directly compare with sibling tools for when to use this vs others like polymarket_edges.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral detail: caching (1h KV-level), model segments, output fields (edge_pp_net, kelly_fraction, 24h-move warning), and why Fed bets are excluded. No contradictions.

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

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

The description is lengthy but well-structured with segments and clear formatting. It front-loads the purpose and uses lists. While detailed, every sentence adds value, so it's appropriately sized 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?

Despite lacking an output schema, the description thoroughly explains the output structure (by_segment, fed_candidates, _diagnostics) and what each opportunity includes. All 9 parameters are documented in the schema, and caching behavior is mentioned. The description is complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, providing baseline parameter descriptions. The description adds context like 'Tradeable-edge knobs' and explains logic for min_kelly, min_partition_leg_kelly, and slippage_pp, enhancing semantic understanding beyond the schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes itself from related siblings like polymarket_arbitrage by emphasizing broad discovery without paging.

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 positions the tool for 'what should I bet on today' and mentions tradeable-edge knobs for filtering, providing clear usage context. However, it does not explicitly state when to use alternatives or exclude cases, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: it's read-only, provides time-series data, trend classification, decay rate, and explains response structure (tracked, expired, snapshot_dates). There is no contradiction.

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

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

The description is front-loaded with the core purpose and uses formatting for readability. It is thorough but slightly verbose; some details like response format could be in an output schema if one existed, but given its absence, the detail is justified.

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

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

Despite no output schema, the description fully explains return values (tracked, expired, snapshot_dates) with field details and limits (TTL, gaps). Parameter schema is already complete. The description provides all necessary context for the agent.

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

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

Schema coverage is 100% with clear descriptions (e.g., 'Lookback in days (default 14, clamp 2-30)'). The description repeats some of this and adds minor context (e.g., 'snapshot family'), but does not add significant new 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 provides edge persistence and decay telemetry from daily snapshots, answering specific questions like 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings by explicitly contrasting with a fresh vs old wide edge scenario.

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 when to use the tool (to understand edge persistence) and mentions limits like 60-day TTL and snapshot gaps. However, it does not explicitly state when not to use or directly compare to alternatives like polymarket_edges, though the context of 'different trades' implies a use case.

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, openWorldHint, idempotentHint as true, and destructiveHint false, so the description doesn't need to restate safety. It adds behavioral context beyond annotations: walking the order book ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, per-leg fill detail, thin_legs, and forced_directional_risk. It also warns about the dominant loss mode. However, some details (e.g., clamp range) are in the schema, so credit for added context but not over-scored.

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

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

The description is relatively long but well-structured with clear sections (SINGLE-MARKET, BASKET) and ALL CAPS for emphasis. Every sentence adds value, but some redundancy (e.g., repeating 'default 1000') and verbose phrasing could be trimmed. Still, it remains focused and front-loaded.

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

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

There is no output schema, so the description must fully explain return values. It does: for single-market, it lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket, it lists theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk. It also covers edge cases (thin legs, partial fills, directional risk). Given the complexity, the description 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%, but the description significantly adds meaning: it explains the two modes for parameters (single-market vs basket), the interpretation of size_usd in each mode (spend vs target proceeds vs shares per leg), the default for side (auto in basket mode), and the clamp range 10-1,000,000. This provides crucial context 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 explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and is distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial basket fills cause unhedged directional risk) and specifies requirements (market or event).

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 read-only/idempotent/non-destructive, and the description goes far beyond that: it discloses that legs with unknown metric_type or match_subtype are never paired, that compatibility_codes can be non-empty alongside matched_pairs, that topic-mode pairings are keyword-matched rather than resolution-source verified, and that most pre-mapped topics currently return warnings. This is exemplary behavioral disclosure.

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

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

The opening sentence front-loads the purpose and the mode/response/safety breakdown follows logically. It is quite long, and some definitions (e.g., code list, counters) could be trimmed or moved to an output schema, but nearly every sentence carries distinct value.

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

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

Given there is no output schema, the description compensates by enumerating response fields, safety flags, code meanings, skipped-pair counters, and temporal alignment. The main gaps are the behavior when no parameters are supplied and a concrete return shape/example, especially for a tool with 0 required params.

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

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

Schema covers 100% of parameters with descriptions and the description adds mode semantics: topic is a shortcut and the two explicit params override the topic-mapped side. It clarifies the relationship between the three params and explains that explicit ticker/slug create custom pairings, adding meaning beyond raw 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 identifies the tool as computing cross-venue probability spreads for the same resolving question on Kalshi and Polymarket, with two invocation modes. It is specific enough that an agent won't confuse it with generic research tools, but it never explicitly contrasts it with sibling tools like polymarket_arbitrage, so it falls short of full sibling differentiation.

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

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

Explicitly lays out two modes (pre-mapped topic vs explicit ticker/slug), explains when custom pairings are used, and tells the agent to treat pre-mapped topics as unverified and often warning-prone. It doesn't explicitly say when to prefer this tool over sibling spread/arbitrage tools, so no exclusions are 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?

Adds scoping detail (anonymous IP, key hash, account ID) beyond annotations which already indicate read-only/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 efficient sentences, front-loaded with core function, 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?

Covers usage, scoping, and pairing; no output schema required; incomplete only if one needs exact return format.

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 key parameter completely; description adds context about pair with remember but doesn't add new semantic details.

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

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

Explicitly states it retrieves a saved value or lists keys, distinguishing it from siblings 'remember' and 'forget'.

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

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

Clearly states when to use (look up previously stored context) and scoping, but does not explicitly 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?

The description claims that setting mark_read:true flags events as read and affects subsequent calls, implying state mutation, but annotations declare readOnlyHint=true. This is a contradiction, and per instructions, the score must be 1.

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—four sentences front-loading the purpose, with no redundant information. Every sentence adds value.

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

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

Tool has 5 optional params, no output schema. Description covers return fields and filtering/polling behavior, but does not detail pagination or unread_only behavior. Overall fairly complete for a read tool.

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

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

Schema covers 100% of parameters; description adds value by providing an example for type ('sec_8k'), clarifying the use of ISO timestamps for since, and explaining the effect of mark_read. This exceeds the baseline of 3.

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

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

The description clearly states the tool retrieves recent alerts from the subscription feed, specifying return fields (source, citation_uri, raw event payload) and filtering options. It is well-distinguished from sibling tools which cover subscriptions, searching, or other actions.

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 provides usage guidance: filtering by type and/or since, setting mark_read, and notes on polling. It also mentions an alternative GET endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it fans out to multiple sources, describes fallback logic (GDELT→GNews), notes USPTO soft-fails until reactivated, and details the return structure (changes[], total_changes, URIs). Annotations already confirm readOnly and idempotent, so the description enriches understanding.

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. It begins with intuitive example queries, then explains core functionality, sources, parameter details, and return format. Every sentence adds value; no redundancy or fluff.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fails) and lack of output schema, the description thoroughly covers return values, source behavior, and alternative tool (entity_profile). It is fully actionable for an AI agent.

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

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

Schema coverage is 100%, but the description enhances parameter understanding: it explains 'since' accepts ISO date or relative shorthand (e.g., '30d'), gives a default recommendation ('30d or 1m'), and clarifies 'value' can be ticker or CIK. This adds practical guidance beyond schema min/max.

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 in the last N days/weeks/months' and lists specific sources (SEC EDGAR, GDELT→GNews, USPTO). It differentiates from the sibling 'entity_profile' by directing users to that tool for static profiles.

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

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

Explicit usage examples ('What's new with X', 'latest on Y') are provided, and the description advises using 'entity_profile' instead for static profile needs. It also explains fallback behavior (GDELT preferred, GNews when rate-limited). However, it doesn't exhaustively list when not to use this tool.

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

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

Annotations already provide idempotentHint=true, but description adds valuable context about scope by identifier, persistent vs. anonymous session retention, and storage as key-value pairs. 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?

Three well-structured sentences: first states purpose, second provides usage guidance, third adds behavioral details. 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?

Complete for a simple memory tool: no output schema needed, description covers all aspects (what, when, how stored, retention), and sibling tools are referenced.

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 enhances with concrete key naming examples and explains the purpose of key-value pair storage beyond schema descriptions.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, provides concrete examples (resolved ticker, target address, etc.), and distinguishes itself from sibling tools 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 tells when to use ('when you discover something worth carrying forward') and mentions alternatives (recall, forget) for retrieval and deletion.

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 readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI is unavailable (EDGAR IDs still return), labels identifiers by source, and explicitly lists unresolved identifiers rather than omitting them. This exceeds annotation coverage.

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 front-loaded with the core purpose and usage guidance. Every paragraph adds relevant detail (supported types, fallback behavior, internal cascading). It could be trimmed slightly without losing meaning, but it is well-organized and purposeful.

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

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

Despite having no output schema, the description explains return characteristics: canonical identifiers, source labels, explicit unresolved entries, and graceful degradation. It covers accepted input forms and edge cases (e.g., non-US issuers). A concrete output example would increase completeness, but the description is sufficient for an agent to use the tool correctly.

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

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

The schema already covers both parameters with descriptions (100% coverage), establishing a baseline of 3. The description adds extra meaning: for 'company' it explains that ISIN resolves to the legal entity via GLEIF mapping, and for 'drug' it clarifies the return includes RxCUI, ingredient, brand, and a citation. This adds value beyond the schema fields.

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 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides specific query examples ('What's the ticker for…'). It distinguishes this tool as the entry point for name-to-ID resolution, contrasting with siblings like entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives concrete examples of when to invoke it. It also notes it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools to use after or instead of this one, so guidance is strong but not exhaustive.

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 non-destructive. Description adds behavioral details: probes multiple entities, ranks results, includes confidence and signal density. 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?

Three sentences, each earning its place: purpose, method, and use case. Front-loaded with key action ('Compare AI visibility...'). No wasted words.

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

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

Given full schema coverage, clear annotations, and a description that explains inputs, behavior, and output (ranked list with score, confidence, signal density), the tool is well-specified. No output schema needed for the explained return format.

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 (100% coverage). Description adds meaning: 'First entry treated as the subject for narrative' and clarifies the purpose of models and _apiKey. Enhances beyond schema.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely more general).

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 an explicit use case ('competitive AI-marketing audits') and an example question. While it doesn't directly contrast with alternatives like ai_visibility_check or compare_entities, the context makes it clear when to use this multi-entity comparison tool.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out across two services, returns specific fields, handles partial failures gracefully, and mentions that bundlephobia's first measurement can take 5-30s and may time out (sources_failed listed). 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 paragraph but efficiently packs essential information. It is front-loaded with the core purpose. A slightly more structured format (e.g., bullet points) could improve readability, but every sentence adds value. It is detailed yet not overly verbose.

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

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

With no output schema, the description fully covers return values: summary block fields, per-advisory detail, links, and alternative versions. It also addresses edge cases (partial failures, ecosystem limitations) and provides usage context. The description is comprehensive for a tool of this complexity.

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

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

Schema has 100% description coverage for both parameters, so baseline is 3. The description adds minimal extra beyond the schema: it implies version defaults to latest (already in schema) and mentions the time-out behavior for the tool, not parameters. No significant enrichment for parameter semantics.

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

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

The description clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data to answer questions about safety, popularity, and size. It distinguishes from siblings by explicitly limiting to npm in v1 and directing other ecosystems to a different tool.

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

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

The description explicitly tells when to use: 'when an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides explicit exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This offers clear guidance 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds rich behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation flagging, and returns character offsets for verification. 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 efficient with 4-5 sentences, front-loaded with the core purpose. Every sentence adds value, though the pairing note could be slightly more concise. Overall well-structured.

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

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

The description covers purpose, use case, technical details (embedding model, windowing, cap), output format (passages with offsets and scores), and pairing with a sibling tool. Despite lacking an output schema, the description provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with thorough descriptions for all three parameters. The tool description does not add significant new semantic meaning beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool does semantic search inside a fetched record, provides concrete examples (SEC 10-K body, article), and distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded. It explicitly says when to use (when record is too big for prompt).

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

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

Explicitly states when to use: when the record is too large for the prompt. It also specifies an alternative workflow: pairing with ask_pipeworx_grounded. The description guides the agent to first fetch the text, then search within it.

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

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

The description discloses behavioral traits such as creation of a subscription, return of subscription id, delivery channel requirements (SMS cap 10/day, phone verification, webhook secret one-time, auto-disable on failure), and persistence constraints. This adds significant context beyond annotations.

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

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

The description is well-structured with clear sections for purpose, supported types, and delivery channels. Every sentence adds value, and it is concise given the complexity of the 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?

The description covers prerequisites, all subscription types with examples, delivery options with specifics (rate limits, verification, webhook details), and return value. It is complete for an agent to correctly select and invoke the tool.

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

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

The description adds substantial meaning to parameters beyond the input schema, including type-specific filter examples (e.g., sec_8k item codes, fred_series series_id) and detailed delivery channel behaviors (webhook HMAC signing, email templating). Schema coverage is 100%, and description significantly enriches it.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', specifying the verb, resource, and outcome. It distinguishes the tool from siblings 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 provides prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist), and detailed examples for each subscription type and delivery channel. However, it does not explicitly state when NOT to use this tool versus alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it returns a curated list of example questions and is the starting point for learning about the system's capabilities, which provides useful behavioral context.

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

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

The description is informative but relatively long; it front-loads example queries but includes some redundancy. It could be slightly more concise while retaining all necessary 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?

Given the tool's simplicity (one optional param, no output schema), the description fully covers its purpose, usage, and expected output, leaving no gaps for the agent.

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

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

Schema coverage is 100% for the single optional parameter, and the description adds examples of topic values (e.g., 'finance', 'pharma', 'betting'), enriching the schema's definition.

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. It explicitly positions itself as the onboarding entry point, distinguishing it from sibling tools like ask_pipeworx or entity_profile.

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

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

The description explicitly says to use this FIRST when unsure what Pipeworx can do, providing clear context. It does not contrast with specific siblings, but the usage instruction is unambiguous.

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 key behaviors beyond annotations: ownership enforcement, deactivation (not deletion), and that historical alerts stay accessible. Annotations already indicate non-destructive and idempotent, and the description adds valuable context.

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

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

Two concise sentences covering purpose, constraints, and side effects. 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?

With a single required parameter, no output schema, and clear annotations, the description fully explains the tool's behavior and constraints, making it complete for agent invocation.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description adds only 'Cancel a subscription by id,' which restates the purpose without adding new parameter-specific meaning. Given 100% schema coverage, baseline of 3 is appropriate.

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

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

The description clearly states it cancels a subscription by id ('Cancel a subscription by id'), distinguishes from deletion by noting it is deactivated, and implicitly differentiates from sibling tools like subscribe and recent_alerts.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. However, no exclusions or alternatives are given beyond the hint that historical events remain available via recent_alerts.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral nuances: the exact meaning of 'could_not_verify' (including the verification_error payload and that it must not be treated as evidence) versus 'unsupported'. It also explains the internal pipeline routing and that evidence is returned with citations, which is far richer than the annotation-only baseline.

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

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

The description is long but every sentence earns its place. It opens with recognizable trigger phrases, then the core purpose, then detailed behavioral notes and a caller warning. It is front-loaded and structured logically, with 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?

The tool is complex and has no output schema, yet the description compensates by fully explaining return values (verdicts, value, citation, reasoning), the error field, and the distinction between failure modes. It covers all important edge cases, making it as complete as needed for reliable invocation and interpretation.

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

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

While the schema already describes both parameters, the description adds strategic guidance for tolerance_pct: how it overrides the wording-implied tolerance, the 1–2 range for hallucination detection, and the default cap of 5. This adds real meaning beyond the schema field 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 performs natural-language claim verification against authoritative sources, with specific trigger phrases and a list of possible verdicts. It distinguishes itself from siblings by noting it replaces 4–6 sequential calls, making its unique role evident.

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

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

It explicitly directs use whenever the agent needs to check factual correctness, and internally differentiates between company-financial claims and other claims with distinct processing paths. However, it does not explicitly name alternative tools or state when *not* to use it, so it stops short of full exclusion guidance.

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