Asana

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. Description adds default model details, optional BYO key for Anthropic with cost implications, and return structure (per-model score/confidence/signals/raw_response + combined view), fully complementing 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?

Description is front-loaded with purpose and provides essential details in a compact paragraph. Slightly long but every sentence is informative.

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

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

Despite missing output schema, description fully explains return format. Covers all aspects: action, parameters, defaults, use cases, and behavioral expectations.

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

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

Schema coverage is 100%, but description adds value by explaining default model (Workers AI Llama-3.3-70b free), cost implications of _apiKey, and the role of context parameter for disambiguation, going 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?

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It distinguishes from siblings focused on general research or entity comparison by emphasizing AI visibility scoring.

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?

Specifies use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and default model behavior. Could explicitly mention when not to use (e.g., for general research), but context is clear.

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

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

Annotations already indicate the tool is not read-only, not destructive, and idempotent. The description adds that it returns task ID, name, and permalink. However, it does not mention potential duplicates or any side effects beyond creation.

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 and to the point. It front-loads the primary action and critical information. Minor redundancy ('task' repeated) 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?

The description covers the main purpose and return values. However, it fails to mention that 'projects' is optional or that 'workspace' can be auto-resolved. The contradiction about required parameters reduces completeness.

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

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

Schema description coverage is 100%, but the description states 'Requires project ID and task name' which contradicts the schema where only 'name' is required and 'projects' is optional. This misleads the agent about parameter requirements.

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

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

The description clearly states the action ('Create a new task in a project') and mentions the return values (ID, name, permalink). It distinguishes from siblings like asana_get_task and asana_list_tasks by specifying it creates a task.

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?

No guidance is provided on when to use this tool versus alternatives like asana_search_tasks or asana_list_tasks. The description mentions required parameters but does not clarify when creation is appropriate or what prerequisites exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds value by listing the specific data returned (e.g., subtasks, tags), but does not mention error conditions or side effects.

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 with no fluff. The most critical information (purpose and requirement) is front-loaded. Every word 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?

Given the output schema exists, the description does not need to explain return values. It lists the main fields covered, and the parameter is simple. The tool is low complexity, and the description is fully adequate.

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

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

The single parameter task_gid is fully covered by the schema description ('Task GID'). The description repeats this as 'Requires task ID' without adding new semantic meaning, so it meets the baseline 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 action ('Get full task details'), specifies the resource (task), and lists included fields (name, description, assignee, etc.). It distinguishes this from sibling tools like asana_list_tasks or asana_create_task.

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

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

The description mentions 'Requires task ID' but provides no explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives like asana_search_tasks. The context is implied but not clearly delineated.

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 (readOnlyHint=true), non-destructive, idempotent, and open world. The description adds that workspace ID is required and lists returned fields, but does not significantly expand on behavioral traits beyond what annotations convey.

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 with no wasted words. The first sentence immediately conveys the core function. Front-loaded and 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 the tool's simplicity, excellent annotations, presence of output schema, and full parameter schema coverage, the description is complete. It covers purpose, return values, and a key requirement.

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 baseline is 3. The description adds value beyond schema by clarifying the necessity of workspace ID (though optional in schema) and stating the output fields, which are not detailed in the input schema.

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

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

The description clearly states the tool lists all projects in a workspace and returns specific fields (ID, name, archived status). This distinguishes it from sibling tools like asana_list_tasks (tasks) and asana_list_workspaces (workspaces).

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

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

The description mentions requirement of workspace ID but does not provide explicit guidance on when to use this tool vs alternatives. Since no other project-listing sibling exists, usage is implied but lacks explicit when-not or alternative references.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which align with listing tasks. The description adds value by specifying the exact fields returned (ID, name, completion, assignee, due date), which is not in the annotations or input schema. 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?

Three sentences, front-loaded with the action and key information. Every sentence is informative and concise. No unnecessary words or repetition.

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 and the presence of a detailed output schema (though not shown), the description covers the essential return fields and required parameter. Sibling tools provide additional context. The description is complete for an agent to select and invoke this tool correctly.

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

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

Input schema coverage is 100% with clear descriptions for each parameter (limit, project, completed_since). The description does not add extra meaning beyond the schema; it mentions 'Requires project ID' but that is already in the schema's required field. 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 it lists tasks in a project, specifying the verb 'List' and resource 'tasks'. It distinguishes from siblings like asana_search_tasks by focusing on a single project and listing all tasks. The returned fields are explicitly mentioned.

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

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

The description states 'Requires project ID', giving a clear context for use. It implies when to use: when you need all tasks from a specific project. However, it does not explicitly contrast with alternatives like asana_search_tasks or asana_get_task, though the sibling list provides 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, openWorldHint, idempotentHint, destructiveHint. The description adds return content context (names and IDs) but does not significantly extend behavioral disclosure beyond that. 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?

Two succinct sentences front-loaded with the primary action and followed by relevant purpose. No unnecessary words or repetition.

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 zero parameters and an output schema (implied complete), the description fully explains the tool's function and return value. Sufficient for a simple list operation.

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 exist, so schema coverage is 100%. The description adds no parameter info, which is acceptable. Baseline for zero parameters is 4.

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

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

The description clearly states the tool returns 'all accessible Asana workspaces' with names and IDs. It distinguishes from sibling tools like asana_list_projects and asana_list_tasks by specifying the resource and hinting at prerequisite use.

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

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

The description implies usage before listing projects/tasks but provides no explicit guidance on when to use vs alternatives or conditions. Context is present but no direct exclusions or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read-only behavior. The description adds that it returns specific fields and requires workspace ID, which is useful but not critical given the rich annotations.

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

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

Two sentences, front-loaded with the core purpose, no wasted words. Every sentence adds value.

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

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

Given the simple search operation, the description covers purpose, return fields, and key requirement. With annotations and output schema, it is reasonably complete. Missing details like pagination or error handling are acceptable.

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 parameters are already documented. The description adds minor context (default limit, max) but has a slight inconsistency: description says 'Requires workspace ID' while schema marks workspace as optional. Since baseline is 3, this is adequate.

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 'Search', resource 'tasks', and scope 'across a workspace'. It specifies the return fields (ID, name, completion status, assignee). This distinguishes it from siblings like asana_list_tasks (which likely lists all tasks) and asana_get_task (single task).

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

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

The description states it uses keyword search and requires a workspace ID (though schema says optional). It does not explicitly exclude when not to use it or mention alternatives, but the context is clear for basic search vs. other task operations.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description adds value by disclosing routing mechanics (fills arguments, returns structured answer with stable citation URIs) and covering live news routing. This goes beyond annotations without contradicting them, though it stops short of detailing rate limits or failure modes.

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 most important guidance ('PREFER OVER WEB SEARCH') and structured logically: what it does, when to use it, examples, alternatives. Every sentence contributes useful context, though it could be trimmed slightly without losing meaning, hence 4 rather than 5.

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 highly complex tool (5,529 tools, 1455 sources), the description covers purpose, examples, domain scope, output format (structured answer with citations), and comparative alternatives. There is no output schema, but the description explains the return value adequately. Combined with rich annotations, the context is 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?

The input schema has 100% coverage of all six parameters, documenting each alias and the main 'question' parameter with examples. The description contributes little extra semantic meaning for parameters, but the schema is sufficiently self-explanatory, so a baseline score of 3 is appropriate.

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

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

The description clearly states that the tool answers factual questions by routing to one of 5,529 tools across 1455 verified sources, returning structured answers with citations. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making its purpose unmistakable.

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

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

The description provides explicit when-to-use and when-to-step-up guidance: prefer over web search, use as default entry point, and step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part questions. Examples are given to illustrate appropriate queries, leaving no 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?

The description discloses the beta/experimental nature, live candidate routing changes, and the current equivalence to ask_pipeworx. It goes beyond annotations (readOnly, idempotent) by explaining the comparison mechanism and reassuring that it is a full working router, not a stub. No contradictions with annotations.

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

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

The description is concise and well-structured, with a clear opening statement, current status, usage direction, and a reassuring closing. Each sentence contributes essential information without 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 (5,529 tools, dynamic routing), the description completely covers: what it does, how it relates to the stable version, current activity status, usage context, and response shape. No output schema is needed since the description references the same response shape as ask_pipeworx.

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

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

Input schema covers 100% of parameters, each with clear descriptions and aliases. The description adds only that arguments match ask_pipeworx, which is useful context but doesn't enhance schema semantics meaningfully. Baseline 3 is appropriate given the schema's completeness.

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 this as a beta version of ask_pipeworx, specifying it is a 'universal router' with the same 5,529 tools, arguments, and response shape. It explicitly differentiates from the stable ask_pipeworx by noting its experimental routing improvements, making the tool's purpose and distinction unmistakable.

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

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

Usage guidance is explicit: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. It also clarifies the current state (no active candidate) and that it fully functions, which informs when to choose this over alternatives.

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

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

The description goes well beyond the annotations by disclosing the return structure, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the added cost of one extra LLM call. This gives the agent a clear model of expected behavior and failure modes.

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 core purpose, then explains the mechanism, return formats, usage context, and trade-off. No redundant information.

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

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

Despite lacking an output schema, the description fully specifies the success and refusal response shapes, including refusal reason enums and the data truncation case. It also covers use cases and alternatives, making it self-sufficient for an agent.

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

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

The input schema has 100% coverage, describing the 'question' parameter and its aliases clearly. The description does not add further parameter-specific details, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains the full process: same routing as ask_pipeworx, fetching data, and extracting answers only from tool results. This distinguishes it from siblings by emphasizing the grounded extraction and refusal behavior.

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

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

Explicit guidance is provided: use when answers will be quoted/cited/acted on and facts must not be invented (e.g., financial, legal, medical). It also says to prefer ask_pipeworx for casual lookups due to the extra LLM call cost, clearly defining 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: resolver contract (match confidence, alternatives, suggestions), parent_event extractor, news field fallbacks, safety short-circuits for low confidence/closed markets/wide spreads, and resolution-rule risk including cancellation parsing. 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?

Description is very long (~500 words) and packs extensive detail. Front-loaded with core purpose, but subsequent sections are dense. Could be more concise without losing key information.

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

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

No output schema, so description must explain return shapes. It does so thoroughly, covering classifiers, fan-out examples, response shapes (market, analysis, evidence), resolver contract, parent event, news fields, safety mechanisms, and resolution rules. Handles edge cases like low confidence, closed markets, wide spreads, and cancellation risk.

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

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

Schema has 100% coverage with descriptions for all params (market, depth, include_raw). Description adds examples and context for 'market' (slug, URL, question text) and explains 'depth' and 'include_raw' behavior implicitly, but adds marginal value beyond schema descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and output (evidence packet + market-vs-model comparison). Distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by being a general research tool.

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

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

Explicitly says 'Use for "should I bet on X"' etc., and gives classifiers and fan-out examples. Does not explicitly exclude alternatives among siblings or state when not to use, but provides clear context for appropriate use cases.

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

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

Annotations already declare read-only, idempotent, and open-world hints. Description adds valuable behavioral details: data sources (SEC EDGAR/XBRL, FAERS, FDA), metrics returned, sorting by primary metric, citation URIs, and parallel execution. No contradictions.

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

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

Description is dense but efficient, front-loaded with trigger phrases and usage guidance, followed by datasource and behavior details. No repetition of schema or annotations.

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

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

For a tool with 2 parameters and no output schema, description fully covers purpose, data sources, sorting, return format (paired data + citations), and replacement of many lookups. All necessary context present.

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

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

Schema coverage is 100%, baseline 3. Description enriches by explaining what each type enum value means (pulls specific data), and provides examples for values parameter (tickers/CIKs for company, drug names). Adds meaning beyond schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and resource 'entities'. It distinguishes from single-entity lookups via explicit preference statement.

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

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

Provides explicit trigger phrases, states when to use (comparing entities), and strongly advises against sequential single-pack lookups. Implicitly excludes single-entity use cases, making usage boundaries clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behaviors: account/auth requirements, paid plan for 'thorough', gap recovery semantics ('gaps[]... never invented'), contradictions[] scan, citation_uri only when resolvable, semantic excerpting, latency ranges, and the use of 'hop' fields. This far exceeds what annotations provide.

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

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

Although lengthy, the description is information-dense and every sentence earns its place. It is front-loaded with the critical account requirement, then logically flows through core function, usage guidance, technical details (gaps, contradictions, citations), and latency. There is no fluff or redundancy.

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

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

Given no output schema, the description fully specifies the return packet: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', plus 'gaps[]', 'contradictions[]', and 'hop' fields. It also covers latency, semantic excerpting, and limitations for non-catalog topics, making the tool's behavior fully predictable.

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 both parameters, but the description adds meaning beyond the schema: it clarifies that 'question' can be broad/multi-part ('Broad/multi-part is fine'), and elaborates on depth semantics with details about gap recovery, contradiction scans, and the paid tier for 'thorough'. This adds real value over the structured schema alone, though baseline is already 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 identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'Decomposes your question into focused facets' and routes each facet to specialized tools in parallel. It explicitly distinguishes itself from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups. The verb+resource is specific and the scope is unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and provides direct alternatives: 'For a single lookup use ask_pipeworx' and for breaking/current news 'prefer ask_pipeworx'. It also states the account requirement and paid tier for thorough depth, making selection criteria very clear.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds that results include 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 that is information-dense but not overly long. It could benefit from bullet points or clearer separation of usage guidance vs. return details, but remains 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?

With no output schema, the description fully explains the return value: top-N tools with names, descriptions, and schemas. It also covers the tool's role as a first-call discovery tool, leaving no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds usage examples and clarifies aliases ('Accepts task, q, description, search as aliases.'), which helps an agent understand flexible invocation.

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

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

The description begins with 'Find tools by describing the data or task' and enumerates many specific domains (SEC filings, financials, FDA drugs, etc.), making the purpose concrete and differentiating it from sibling tools that perform specific data retrieval.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use and implies when not to (if you already know the tool).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description goes well beyond by detailing the fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, listing exact return fields (cik, recent_filings with URIs, fundamentals sorted by period_end, patents with soft-fail note, LEI). This provides rich behavioral transparency without contradicting annotations.

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

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

The description is a single dense paragraph that front-loads purpose ('full cross-source profile in ONE call'), lists trigger phrases, and details return data. While effective and concise, a more structured format (e.g., bullets) could improve readability, but overall it is appropriately sized with no waste.

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

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

Given the tool's complexity (multiple data sources, soft-fail condition, specific input formats) and lack of output schema, the description fully covers behavior, inputs, and return structure. It mentions patent deprecation (soft-fail), URI format for filings, and sorting of fundamentals, making it complete for agent usage.

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 params. The description adds crucial operational context: value must be ticker or zero-padded CIK, names not supported, and type enum limited to 'company' with future plans. This adds meaningful usage guidance beyond schema.

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

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

The description states the tool produces a 'full cross-source profile of a US public company in ONE parallel call'. It lists concrete example queries ('Tell me about X', 'research Acme', etc.) and explicitly distinguishes itself from chaining multiple single-source lookups, making its purpose very clear 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?

The description explicitly advises 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view', and clarifies that names are not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance with 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?

Matches annotations (destructiveHint=true). Adds context about sensitive data clearance and appropriate use cases beyond what annotations provide.

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

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

Two sentences, zero waste, action first, clearly structured.

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

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

Given simple schema (1 param, no output), description covers purpose, use cases, and pairing comprehensively.

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 no additional meaning beyond the schema's 'Memory key to delete'.

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

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

Clear verb ('Delete') and resource ('previously stored memory by key'). Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Also suggests pairing with 'remember' and 'recall', providing context for selection.

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

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

Describes the exact process (fetches, extracts, emits) and output format, adding value beyond annotations (readOnlyHint, idempotentHint). No contradictions; the description aligns with and elaborates on the non-destructive, idempotent behavior.

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

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

Two sentences with zero redundancy. First sentence firmly establishes purpose and audience; second details process and output form. All information is front-loaded and every phrase 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?

Explains output nature ('single text blob') and practical deployment location. With 100% schema coverage and strong annotations, additional details (e.g., error handling, rate limits) are unnecessary. Slightly incomplete on what happens when extraction fails, but acceptable.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minor context ('key links' indicates intelligent selection) but does not significantly enhance understanding beyond the schema itself. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifies the AI crawlers it targets, and contrasts with siblings like scan_competitor_ai_presence. The verb 'generate' plus resource 'llms.txt' is specific and distinct.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Provides clear context but does not include when-not-to-use scenarios, though the tool’s specificity makes exclusions implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it lists active subscriptions by default and includes return fields, enhancing transparency.

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

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

Two sentences: first states purpose and returns, second gives usage guidance. No fluff, 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?

Complete for a simple tool: explains return fields, usage, and parameter. Output schema not needed.

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

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

Schema covers the one parameter fully. Description adds default value ('default false') and clarifies 'inactive' as 'cancelled', adding meaning beyond schema.

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

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

Description explicitly states 'List the caller's active subscriptions' with a clear verb and resource, and lists return fields, distinguishing it from sibling tools like subscribe/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?

Provides context for use: 'review what you're monitoring before adding more or to find an id to cancel.' No explicit exclusions, but clear enough.

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

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

Annotations provide no safety signals (all false), so the description carries the burden. It adds meaningful behavioral disclosure: claim_token flow for anonymous filing, rate limit of 5 per identifier per day, no quota impact, and that reports are read daily. It could be even stronger by stating explicitly whether reports are stored or transmitted externally, but the given context is substantial.

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?

Though longer than typical tool descriptions, every sentence adds necessary information: purpose, usage categories, exclusions, claim-token mechanics, rate limits, quota impact, and roadmap signal. It is front-loaded with the primary purpose and structured logically from 'what' to 'when' to 'how', making it easy to scan.

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

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

Given no output schema, the description adequately covers return behavior by mentioning the claim_token returned on filing and the ability to later check status and changes. It handles the tool's complexity (4 parameters, nested context, multiple feedback types) well, and sibling tool context confirms this is a special-purpose tool that needs no cross-referencing to other tools.

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds valuable semantic context beyond the schema, especially for claim_token: it explains the full flow of receiving a token and passing it back later. It also offers guidance on message content (describe in terms of Pipeworx tools, don't paste user prompt), which enriches the understanding of the message parameter.

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

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

The description leads with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx feedback). It distinguishes this tool from all sibling tools by framing it as the channel for reporting bugs, feature requests, data gaps, and praise, which is unique among the listed tools.

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

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

Provides explicit when-to-use guidance via enumerated categories (bug, feature, data_gap, praise) and gives a clear exclusion criterion: only for tools served by this Pipeworx connection, not other MCP servers. It also explains when to defer and what to do when unsure, plus practical constraints like rate limits and daily digest.

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 value by explaining the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h depending on window), and the nature of the returned data (aggregate call volume). No contradictions.

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

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

The description is concise and well-structured: first sentence gives the core functionality, followed by bullet-like use cases, then additional context about data source and caching. Every sentence adds value with no redundancy.

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

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

Given the tool has one optional parameter, no output schema, and is read-only/observational, the description fully covers what an agent needs to know: what it returns, when to use it, data provenance, caching, and privacy. It is comprehensive for its complexity level.

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

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

Schema coverage is 100% with one parameter (window) having an enum and description. The description adds behavioral context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which 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 tool returns top tools, packs, and total call volume over configurable time windows. It lists three specific use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and differentiates itself from sibling tools that perform search or specific data retrieval.

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

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

The description explicitly provides three concrete scenarios where the tool is useful (discovering hot data sources, confirming canonical choice, alignment check). It does not explicitly state when not to use it, but the context and sibling list imply this is for aggregate trending data, not for point queries.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: partition filter dropping placeholder slugs, semantic anchor with Jaccard similarity, fill check against live CLOB depth, and edge cases like skipped_low_similarity. 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 somewhat verbose but well-structured: it starts with core purpose, then details each mode, followed by semantic anchor, partition filter, response format, and fill check. Front-loading key information helps AI agents quickly grasp usage. Some technical detail could be condensed, but every paragraph adds necessary context.

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

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

Despite no output schema, the description thoroughly covers return format (opportunities[] with fields, event mode partition_check, fill check) and edge cases (placeholder filtering, similarity threshold, fill risk). It also references sibling tool polymarket_fill_risk for custom sizing, showing awareness of the tool ecosystem.

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 descriptions are present for both parameters (100% coverage). The description adds value by explaining each parameter's usage context, acceptable inputs (slugs, full URLs, seed questions), and which mode to use. This goes beyond the schema definitions, though schema already provides basic descriptions.

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

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

The description clearly specifies the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It differentiates three modes (no args, event, topic) and distinguishes from sibling tools like polymarket_edges by specifying unique functionality.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also notes cross-event mode catches patterns missed by single-event mode, and warns about fill checks.

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 extensive behavioral details beyond the annotations, including caching (Cached 1h at KV level), model specifics, response structure, and edge-case handling. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces these with no contradictions.

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

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

The description is well-structured with sections for each model family and response elements. However, it is quite long (multiple paragraphs) and could be more concise, though the complexity of the tool warrants the detail.

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

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

Given 9 parameters and no output schema, the description fully covers what the tool returns (by_segment, diagnostics, fed_candidates), explains why segments might be empty, and describes caching. It is comprehensive and leaves little ambiguity.

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

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

The input schema has 100% coverage, and the description adds significant meaning to each parameter, explaining how they affect results (e.g., slippage_pp subtractions, tradeable-edge filters). It provides context beyond the schema, especially for min_kelly and min_partition_leg_kelly.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it mentions specific model families. However, it does not explicitly differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', though the detailed model descriptions imply uniqueness.

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

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

The description explicitly states the tool is built for 'what should I bet on today' and that it avoids paging hundreds of markets. It provides guidance on tradeable-edge knobs and explains how to interpret empty segments. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral detail: the exact response structure (tracked, expired, snapshot_dates arrays), field semantics (trend, decay_pp_per_day, lifespan_days), and limitations (TTL, snapshot gaps, decay calculation basis). 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 moderately lengthy but every sentence contributes value. It is well-organized: purpose first, then detailed response layout, then limits. Could be slightly tightened but remains efficient for the complexity.

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

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

With no output schema, the description fully defines the return structure and field meanings. It covers input parameters, output arrays with semantics, and limitations. Given the tool's complexity (time-series analysis), 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 coverage is 100% with descriptions for both parameters. The description adds context: default days=14, max 30 (consistent with schema's clamp 2-30), window default '1wk', and explains window as 'snapshot family'. This adds useful meaning beyond the schema labels.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' from 'daily polymarket_edges snapshots'. It answers a specific question about edge age and trend, distinguishing it from related tools like polymarket_edges that likely provide raw current edge data.

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

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

The description provides implicit usage guidance by contrasting a fresh edge with an old one, signaling when this tool adds value. It does not explicitly list alternatives or when not to use, but the context is clear enough for an agent to infer appropriate use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral depth about order-book walking, return fields (verdict, slippage, etc.), and risks of partial fills. No contradiction; the description enriches the annotations without redundancy.

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

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

The description is dense but well-structured with bullet-like formatting and ALL CAPS for key terms. It is front-loaded with the purpose and effectively uses whitespace, though could be slightly more concise. 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?

Despite lacking an output schema, the description thoroughly lists return fields for both modes (top_of_book, vwap_fill_price, slippage, etc.) and explains the verdict. It covers the tool's complexity (two modes) comprehensively, leaving no major gaps for the agent to guess.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description goes further by clarifying mode-specific meanings for size_usd (spend vs proceeds vs notional) and default values, adding meaning beyond the schema.

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

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

The description clearly states the tool is a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields, making the purpose unambiguous and differentiating from siblings 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?

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why with concrete risks like overround capturability and partial-fill directional exposure, providing clear when-to-use and when-not-to-use 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?

Adds significant detail beyond annotations: safety fields (compatibility_warning, temporal_alignment, skipped counters), modes, and semantic mismatch caveats. Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false; 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Front-loaded main purpose. Slightly long but justified by tool 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?

No output schema, but description thoroughly explains response structure (leg prices, top_spreads_pp, safety fields). For a 3-param tool with no required params, coverage is excellent.

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

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

Schema coverage 100% (parameters described). Description adds operational context: topic macros list, explicit overrides, interaction logic. Slightly redundant with schema but adds value.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic and explicit) and explains output. Differentiates from sibling polymarket_arbitrage.

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 (cross-venue spread) and when compatibility_warning indicates no arbitrage. Caveats about pre-mapped topics often returning warnings. No explicit alternatives but sibling list provides 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping details ('Scoped to your identifier') and the effect of omitting the key (list all keys), providing 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?

Two sentences, each earning their place. The first states the core function, the second adds context. No redundancy or wordiness.

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

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

For a read tool with no output schema, the description covers what to expect (value or list of keys), scoping, and usage. It could mention potential output limits or pagination, but overall it is sufficiently 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%, but the description adds meaning: 'omit the key argument' to list keys. It clarifies the single parameter's two modes, improving 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 specifies 'Retrieve a value previously saved via remember, or list all saved keys', clearly identifying the verb and resource. It also distinguishes from siblings by mentioning 'remember' and 'forget', which are listed as sibling tools.

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

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

The description provides explicit guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also implicitly advises when not to use (for saving or deleting) by pairing with remember and forget.

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

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

Adds detail beyond annotations: describes return payload fields, mark_read effect on subsequent calls, and polling suitability. 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?

Five sentences, informative but slightly verbose. Front-loaded with main action, but includes extra detail on alternative access at the end.

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 main purpose, return fields, filtering, and mark_read. Lacks explicit mention of list structure or pagination, but is adequate for a read-only tool with good schema coverage.

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

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

Schema coverage is 100% so baseline is 3. Description adds concrete example for 'type' ('sec_8k') and explains 'mark_read' side effects, but 'limit' and 'unread_only' lack additional context.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. No sibling tool fetches alerts, so it is well distinguished.

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 context on filtering by type/since, mark_read behavior, and notes polling works fine. Also offers an alternative access via GET URL, but does not explicitly exclude other 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?

Beyond annotations (readOnlyHint, etc.), the description details multi-source fan-out, fallback mechanisms, and soft-fail behavior (USPTO PatentsView API sunset). This gives the agent comprehensive understanding of the tool's internal behavior and failure modes.

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

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

The description is front-loaded with example queries and organized into sources, fallback, and return format. While comprehensive, it is slightly verbose but still efficient given 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?

The tool has no output schema, but the description explicitly mentions return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). Combined with fallback and error behavior, the description is thorough and self-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%, but the description adds practical usage guidance: e.g., 'Use "30d" or "1m" for typical monitoring' for 'since', and explains 'value' can be ticker or CIK. This adds semantic value beyond the schema's brief descriptions.

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

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

The description explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and clarifies it aggregates SEC, news, and patents. It distinguishes from the sibling tool 'entity_profile' which provides static profiles, fulfilling the need for 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?

Description offers clear guidance on when to use this tool vs. alternatives: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains fallback behavior (GDELT→GNews) and provides parameter usage examples.

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 context beyond annotations: key-value scoped by identifier, persistent vs. temporary memory (24 hours for anonymous). No contradictions with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four sentences, well-structured: purpose first, then usage guidance, then behavioral details. 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?

Covers purpose, usage, persistence, and relationships to other tools (recall, forget). No output schema needed for a store operation; effect is clear.

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 good parameter descriptions. The description adds no extra parameter-specific meaning beyond what's in the schema, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later across conversations or sessions.' It specifies the resource (key-value pairs) and verb (save/remember), and distinguishes from siblings like 'forget' and 'recall' by mentioning them.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward.' Also mentions when not to use indirectly by pairing with recall and forget, providing clear context.

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

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

Despite the helpful annotations (readOnly, idempotent), the description adds substantial behavioral context: graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI are down), explicit `unresolved` reporting, and internal cascading through endpoints. It also clarifies source labelling and parent/ownership data, which is not evident from the schema.

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

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

The description is longer than average but well-structured with sections for usage triggers, supported types, and fallback behavior. Each sentence adds information, and the example queries serve as useful triggers for an AI agent. The length is justified by the tool's complexity, though it could be condensed slightly.

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

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

Given the absence of an output schema, the description does an excellent job of describing return values: it lists the identifiers for each type, notes the source labels, and explains how unresolved identifiers are handled. It also covers edge cases like LEI/FIGI unavailability and internal workflow, making it highly complete for an agent to invoke.

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 100% of parameters with descriptions and examples, so the baseline is 3. The description enriches the `type` parameter by explaining what each entity type returns (company: CIK/ticker/LEI/FIGI; drug: RxCUI/ingredient/brand) and clarifies the accepted `value` formats, going beyond the schema's one-line descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers (ticker, CIK, LEI, RxCUI, etc.) and explicitly says 'Use FIRST whenever you have a name but need an ID.' It distinguishes itself from sibling tools by framing it as the prerequisite for other tools and by not causing ambiguity with similar tools like entity_profile or compare_entities.

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

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

The description provides explicit context for when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a perfect 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds how the tool probes each entity, calls ai_visibility_check, and returns a ranked list with score, confidence, and signal density. 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?

Three concise sentences front-load the main purpose and functionality, with no wasted words. Every sentence adds value.

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

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

With full schema coverage and annotations, the description explains the tool's workflow, expected output, and use case. No output schema, but the description covers return fields adequately.

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

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

Schema description coverage is 100%, so baseline 3. The description adds semantic context: first entity treated as 'subject' for narrative, and default model is workers-ai. This provides guidance 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly recommends the tool for competitive AI-marketing audits with an example question. It implies when to use but does not provide explicit when-not-to-use or list alternatives.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. Description adds that the tool fans out to multiple services, returns specific fields, and mentions partial failures (sources_failed) and timing (5-30s for bundlephobia first measurement). No contradictions.

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

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

Description is somewhat long but front-loaded with purpose. Each sentence adds information, though could be streamlined slightly. Good structure with clear sections.

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 description thoroughly explains the return data (summary fields, advisory details, links, alternative versions) and behavior on errors (sources_failed). Covers all necessary context for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter descriptions (package accepts scoped names, version defaults to latest). Acceptable but no extra 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 clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings (none focus on npm packages).

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'' and notes 'NPM ecosystem only in v1' with alternatives for other ecosystems. Provides guidance on partial failures and timing.

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

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

Annotations already declare readOnly, idempotent, openWorld, and not destructive. Description adds implementation details: embeddings model, window size, character cap with truncation flag, and return fields. 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?

Two paragraphs, about 120 words, no fluff. Core purpose is front-loaded, followed by technical details and usage guidance. 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?

Covers use case, technical details, limits, and pairing guidance. Lacks explicit output format specification but mentions return fields. Could be more complete with edge-case handling, but overall adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides usage examples for the query parameter but does not add significant new meaning beyond what the schema already provides.

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

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

The description clearly states it performs semantic search inside a fetched record, with a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and context-saving benefits.

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 big to cram into the prompt'. Also provides a workflow pairing with ask_pipeworx_grounded, but lacks explicit when-not-to-use conditions.

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 set readOnlyHint=false and destructiveHint=false. The description adds behavioral details: returns subscription ID, delivery channels always on feed, optional email/SMS/webhook with constraints (SMS 10/day cap, webhook auto-disable after 10 failures). It enriches the annotation context.

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

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

The description is front-loaded with the core purpose and returns information. It is dense but efficient given the complexity of the tool (multiple types, delivery channels). Could be slightly more concise, but structure is logical with clear sections.

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 and three parameters including nested objects, the description covers all essential aspects: auth requirements, type-specific parameters, delivery options, and constraints (phone verification, rate limits, webhook failure handling). No crucial information 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%, but the description goes far beyond the schema. It provides concrete examples for each type (e.g., sec_8k with items codes, polymarket_edge with topic) and elaborates on delivery channel options (email, SMS verification, webhook signing). This adds substantial meaning.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value ('Returns the new subscription id'). It effectively distinguishes from sibling tools like list_subscriptions (viewing) and unsubscribe (removing).

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 usage prerequisites (requires Pipeworx OAuth account) and type-specific parameter guidance but does not explicitly contrast with sibling tools (e.g., list_subscriptions, unsubscribe). It lacks explicit when-to-use and when-not-to-use guidance relative to 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds transparency about the return content (category-bucketed examples with exact tool+argument shape) and that it draws from a live catalog. This is useful context beyond the annotations, though the annotations already cover safety.

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

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

The description is a single paragraph, front-loaded with example queries. It is fairly long but every sentence adds value. Minor verbosity for a simple tool, but not excessive.

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

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

For a tool with one optional parameter and no output schema, the description covers what it does, when to use, and what to expect. It is fully adequate for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% for the single optional parameter (topic). The description enriches by listing valid focus areas (finance, pharma, etc.) and clarifies that omitting the argument gives a full cross-category spread. This adds practical value beyond the schema 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 identifies the tool as an onboarding entry point that returns example questions bucketed by category. It specifies the verb ('returns') and the resource ('category-bucketed example questions'), and distinguishes it from siblings by positioning it as the first tool to use when learning about Pipeworx.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on optional argument usage ('Call with no arguments for the full spread, or pass `topic` to focus'). While it doesn't explicitly list when not to use, the context is strong.

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

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

Discloses key behaviors beyond annotations: ownership enforcement, deactivation instead of deletion, and reference to 'recent_alerts' for history. Complements annotations (idempotent, non-destructive) with concrete details.

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

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

Two concise sentences, front-loaded with the action and enforcement, no fluff. 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?

Covers purpose, behavior, and ownership. For a simple one-param tool, it is nearly complete. Lacks mention of return value, but no output schema exists, so not critical.

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

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

With 100% schema coverage, the description adds no new parameter detail beyond what the schema provides. The mention of 'by id' aligns with the schema, but no additional 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?

Clearly states 'Cancel a subscription by id', specifying the verb and resource. Distinguishes from sibling tools like 'subscribe' and 'recent_alerts' by describing deactivation behavior and linking to historical events.

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

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

Explicitly notes ownership enforcement and that deactivation preserves historical data, which guides when to use this tool vs alternatives. However, it does not explicitly mention when not to use or compare to other cancellation methods.

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 readOnlyHint and idempotentHint annotations. It explains the two routing paths (SEC EDGAR vs grounded pipeline), the exact meaning of each verdict, and especially the critical distinction between could_not_verify (check did not happen) and unsupported (no source exists). This is essential behavioral context for callers.

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

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

The description is longer than average but well-structured, front-loaded with trigger phrases and a clear use case. The 'IMPORTANT for callers' section is necessary and earns its place. Minor redundancy (e.g., 'routed to the right live source, answered with verbatim evidence') prevents a 5.

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 values, verdict types, and error semantics. It covers the tool's complexity, gives a scaling rationale ('replaces 4–6 sequential calls'), and provides enough information for an agent to invoke it confidently without further documentation.

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

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

Schema coverage is 100% and both parameters have descriptions, but the tool description adds meaningful value by explaining tolerance_pct override semantics, the default behavior, and an example claim. This goes beyond what the schema provides, so a 4 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 natural-language claim verification against authoritative sources. It lists explicit trigger phrases and states the specific outcome (verdict, value, citation). This distinguishes it from general Q&A tools like ask_pipeworx and research tools like deep_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear when-to-use directive. It does not name alternatives or give when-not-to-use advice, but the scope is well-defined. Replaces 4–6 sequential calls implies it is the right consolidated tool for claim verification.

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