Nps

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds valuable context: it returns per-model scores, confidence, signals, raw_response, and a combined view. Also transparent about API key pass-through and billing.

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?

Efficient two-sentence description plus a use-case summary. No wasted words; front-loaded with main action and key details.

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

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

Despite no output schema, the description fully explains return structure (per-model fields + combined view) and all parameter roles. With annotations covering safety, this is complete for a moderate-complexity tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds extra meaning: default model when omitted, purpose of _apiKey ('BYO key — you pay Anthropic directly'), and context parameter for disambiguation. Exceeds baseline of 3.

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

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

The description clearly states the tool probes LLMs for brand/topic knowledge and scores visibility 0-100 per model. It distinguishes from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on 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?

Provides clear when-to-use scenarios (marketing audits, pre-launch checks) and explains default model and optional _apiKey for Anthropic. Could explicitly mention when not to use, but sufficient context given sibling list.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by explaining that the tool routes questions, fills arguments itself, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict any annotation, though it omits details on response formatting or failure behavior.

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

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

The description is long but front-loaded and logically ordered: preference rule, supported data domains, routing behavior, trigger phrases, examples, and sibling routing. It is dense and mostly earns its length, though it is slightly overpacked and ends with an incomplete 'use...' phrase, which keeps it from being a top-tier concise definition.

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 broad router nature and the absence of an output schema, the description adequately covers what the tool accepts, why it should be called, what it does with the question, what it returns, and when to prefer alternatives. It could be more complete by specifying the shape of the structured answer, but the mention of stable pipeworx:// citation URIs provides enough context for invocation.

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

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

Schema coverage is 100%, and the only meaningful parameter is 'question' with several aliases, so the baseline is adequate. The description adds value by providing concrete example questions and by stating that the tool fills arguments itself, signaling that the caller should send natural-language intent rather than manually structured parameters.

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

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

The description begins with a strong, specific routing directive: prefer this tool over web search for authoritative current or historical data, followed by a detailed list of domains and the explicit behavior of routing to thousands of sources and returning structured answers with citation URIs. This clearly identifies the tool's purpose and distinguishes it from web search and sibling research tools.

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

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

The description gives both explicit positive triggers ('Use whenever the user asks...', 'START HERE for most questions') and explicit alternatives for distinct cases: deep_research for iterative research, compare_entities for side-by-side comparisons, ask_pipeworx_grounded for exact citations, entity_profile for profiles, bet_research for enterprise data, and search_within for source-level control. An agent can confidently choose this tool versus siblings without inference.

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

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

The description adds substantial behavioral context beyond the annotations: it is experimental, may have routing candidates active, currently matches ask_pipeworx exactly, and 'Falls back to nothing' — emphasizing it is a full working router. This is exactly the kind of operational nuance an agent needs.

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: the first sentence defines the tool, the second gives current status, the third gives usage guidance, and the fourth clarifies fallback behavior. Every sentence earns its place and the most important information is front-loaded.

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

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

For a complex router with no output schema, the description adequately covers identity, behavior, current state, and usage. The only minor gap is that 'same response shape' relies on the agent knowing ask_pipeworx's response format, but that is a reasonable reference given the sibling context.

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

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

Schema description coverage is 100%, with question and all five aliases clearly documented in the schema. The description adds no new parameter-level meaning, only says 'same arguments' as ask_pipeworx, so the baseline of 3 applies.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape, but with candidate routing improvements when under test. This explicitly distinguishes it from the stable ask_pipeworx sibling and explains what makes it different.

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

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

It gives direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It does not explicitly state when NOT to use it or mention alternatives like ask_pipeworx_grounded, but the intended scenario is 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 already mark this as read-only, non-destructive, idempotent, and open-world. The description adds substantial behavioral detail beyond annotations: it guarantees extraction only from tool-result content, returns verbatim evidence, and may explicitly refuse with enumerated refusal reasons. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return contract, refusal contract, use cases, and cost tradeoff. Key information is front-loaded with the purpose and the grounded guarantee, followed by concrete output and refusal details.

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

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

There is no output schema, so the description compensates by describing the exact success and refusal return shapes and all refusal reason values. It also covers when to use, when not to use, cost, and behavioral guarantees, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, and the only required parameter is a natural-language question with aliases well documented in the schema. The description does not add parameter-level detail, but it does not need to because the schema fully covers the input semantics. A baseline of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode that routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from siblings by naming the shared routing and the grounded extraction guarantee, and the success/refusal outcome shape makes its function concrete.

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: high-stakes reads where answers will be quoted, cited, or acted on, and where fact invention is unacceptable. It also names the alternative (ask_pipeworx) and states when to prefer it ('casual lookups'), plus the cost tradeoff of one extra LLM call.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains resolution matching, parent event extraction, news fallback mechanisms, safety short-circuits, closed market handling, wide-spread warnings, and resolution-rule risk. This far exceeds the minimal information from 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 lengthy (multiple paragraphs) and packed with details. It is front-loaded with the core purpose, but some details (like fan-out examples and response shapes) could be condensed or moved to documentation. While scannable, it is not concise.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers all significant aspects: input formats, classifiers, fan-out examples, response structure, resolver contract, parent event extraction, news error handling, safety behaviors, and cancellation rules. An agent can fully understand the tool's behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond the schema descriptions. The 'market' parameter is explained similarly, and 'depth' and 'include_raw' are not elaborated further.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs and outputs. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the use cases ('should I bet on X') provide implicit distinction.

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

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

The description explicitly lists when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not provide when-not-to-use or alternatives, but the use cases are clear and specific.

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. Description adds behavioral details: results sorted by primary metric, returns paired data + citation URIs, handles off-calendar fiscal years correctly. 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?

Concise but comprehensive: 6-7 sentences, each adding value. Front-loaded with natural language examples, then covers data sources, sorting, output format. No wasted words.

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

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

Despite no output schema, the description explains return values (paired data + citation URIs) and notes efficiency (replaces 8-15 sequential lookups). All necessary context for correct agent invocation is 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?

Input schema has 2 parameters with 100% coverage. Description adds meaning: for 'type' enum, it explains data sources for each option; for 'values', it specifies formatting (tickers/CIKs for company, drug names for drug). This enriches the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It begins with natural language triggers and specifies exactly what data is pulled for each entity type, distinguishing it from siblings like entity_profile.

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

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

Explicitly says "ALWAYS PREFER over sequential single-pack lookups" and defines the scope (2-5 entities, types company or drug). This provides clear when-to-use guidance and differentiates from 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond these by explaining decomposition into facets, parallel routing across 5,798 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting of large records, and expected latency. This is rich, non-redundant behavioral disclosure.

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

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

The description is long but every section carries useful information: account requirement, alternative tool, core behavior, ideal use cases, depth semantics, citation behavior, and timing. It is front-loaded with the most critical invocation constraint. Slightly verbose in places, but structure and density justify the length for a complex tool.

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

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

With no output schema, the description carries full responsibility for describing return values. It does so thoroughly: findings packet fields, gaps[], contradictions[], hop field, citation_uri fetchability, and semantic excerpting. It also covers prerequisites, alternatives, depth options, and latency, so an agent has complete context for calling the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by noting that depth:'thorough' requires a paid plan and by clarifying time expectations for each depth tier. The schema already describes quick/standard/thorough mechanics, so the incremental value is moderate but real.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in 'ONE call', and explicitly contrasts with 'NOT open-web search.' It also differentiates from siblings by stating it is best for broad/multi-part questions and pointing to ask_pipeworx for single lookups, so an agent can reliably select this over alternatives.

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

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

The description is explicit about when to use this tool versus alternatives: 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx instead.' It also gives a clear fallback: if not signed in, use ask_pipeworx. This removes guesswork about invocation 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 indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: returns top-N tools with full schemas, ready to call directly, no second schema lookup needed. It does not contradict annotations.

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

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

The description is information-dense and front-loaded with the primary purpose. A few minor redundancies (e.g., listing data sources twice) prevent a perfect score, but it remains concise and well-structured.

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

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

Despite no output schema, the description fully explains the return value (tools with names, descriptions, full schemas) and usage context. It covers examples, data sources, and the intent to provide a complete discovery experience.

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 enriches parameter meaning by explaining the query parameter as 'natural language description' and listing aliases, and clarifies the limit parameter's role in result size.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource ('tools') and action ('find'/'discover'), and distinguishes itself from sibling tools (which are specific data sources) by being a discovery mechanism.

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 'Call this FIRST when you have many tools available' and provides a comprehensive list of use cases. While it doesn't explicitly state when not to use it, the guidance is strong and practical.

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 readOnly/openWorld/idempotent annotations by disclosing fan-out behavior, soft-fails for the USPTO PatentsView sunset, empty-section semantics, resolved:false behavior, and sources_used/sources_failed reporting. There is no contradiction with annotations.

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

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

The description is long, but the tool is complex with many source categories and edge cases. It is front-loaded with user-intent examples and each added clause carries meaningful behavioral information; a shorter version would lose 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?

There is no output schema, so the description carries the burden of explaining returns. It enumerates the profile sections, lists URIs, explains expected empty results, describes failure handling, and covers input options, making it complete for an agent to select and call correctly.

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

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

Schema coverage is 100%, so the schema already documents type and value. The description adds value by giving concrete examples, explaining that type values are interchangeable, and clarifying name resolution and resolved_from/resolved_to behavior beyond the schema.

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

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

The description opens with concrete natural-language triggers and states the resource: a full cross-source profile of a US public company in one parallel call. It clearly distinguishes this from chaining single-pack SEC/XBRL/news lookups and from sibling tools like deep_research or compare_entities.

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

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

It explicitly says to prefer this tool over chaining single-pack lookups when the user asks for a holistic view, and it explains what happens for private companies. However, it does not explicitly contrast with sibling tools like deep_research or compare_entities, so the when-not-to-use guidance is slightly incomplete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and irreversibility, 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, front-loaded with purpose, no wasted words.

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

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

Low complexity tool with one parameter. Description covers purpose, usage, and pairing. Lacks return value or error info, but not critical given simplicity.

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

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

Schema coverage is 100% with clear description of the 'key' parameter. Description does not add meaningful semantics beyond schema.

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

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

Clearly states action (Delete) and resource (previously stored memory by key). Differentiates from sibling tools like 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 lists when to use (context stale, task done, clear sensitive data) and pairs with related tools (remember and recall).

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds details about fetching, extracting, and output format, which goes beyond annotations without contradiction.

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

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

The description is concise (3 sentences plus bullet list) and front-loaded with the primary purpose. Every sentence adds value, and the structure is 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 low complexity, rich annotations, and lack of output schema, the description fully covers what the tool does, how it works, output format, and appropriate use cases, enabling correct invocation.

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

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

Schema coverage is 100% with good parameter descriptions. The description does not add additional meaning beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool generates an llms.txt file for any URL, using a specific verb and resource. It distinguishes itself from sibling tools which do not perform this function.

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

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

The description provides explicit use cases (getting client's site indexed, drafting for own project, auditing competitor), but does not explicitly state when not to use it 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 indicate read-only, open-world, and idempotent behavior. The description adds detail on the rich response (full description, activities, fees, etc.), going beyond the annotations.

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

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

The description is a single, well-structured sentence that conveys the tool's action and return value without unnecessary words.

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

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

For a simple fetch-by-ID tool, the description covers the action, input, and output sufficiently. An output schema likely exists, so no further detail is needed.

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

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

Schema coverage is 100% with a clear description of park_code parameter. The tool description does not add extra parameter semantics but provides context about the expected return, justifying a 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 'Fetch a single park by parkCode' and lists the data fields returned, distinguishing it from siblings like 'list_parks' which retrieves multiple parks.

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

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

The description specifies the tool is for fetching a single park by code, implying when to use it. It does not explicitly exclude cases, but the requirement of a park_code clarifies the primary use case.

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

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

Annotations already indicate safe, read-only behavior. The description adds context that alerts are 'current' and lists types, enhancing transparency. 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?

Single sentence conveys purpose, content, and filtering. No superfluous words; front-loaded with key information.

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

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

Output schema exists, so return structure is covered. Description covers the tool's scope and filtering adequately 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?

Schema coverage is 100% with descriptive parameter documentation. The description reiterates filtering by parkCode or state but adds no new semantic detail 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 lists current park alerts with specific categories (closures, road conditions, weather warnings, danger advisories) and mentions filtering by parkCode or state. This distinguishes it from sibling tools like list_parks or list_campgrounds.

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 indicates filtering options but lacks explicit guidance on when to use this tool vs alternatives like recent_alerts. No 'when not to use' or exclusion conditions are provided.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it returns specific fields, but does not elaborate on pagination, result limits, or any side effects. With annotations covering safety, this is adequate.

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 short sentences that are front-loaded and efficient. Could be slightly more structured (e.g., separating purpose from return fields), but no wasted words.

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

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

Given the output schema exists and parameters are fully covered, the description is minimally complete. It lists return fields but doesn't mention available filters (park_code, state, limit, query) or that results are a list. Adequate but not rich.

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 four parameters. The description does not add meaning beyond the schema (e.g., clarifying typical usage of 'query' vs 'state'). Baseline score of 3 applies as schema already documents parameters.

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

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

The description clearly states the tool lists campgrounds within a park or state, and enumerates the return fields (name, description, capacity, amenities, etc.). It distinguishes from siblings like 'list_parks' by specifying the resource and filter scope.

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

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

No explicit guidance on when to use this tool versus alternatives like 'list_parks' or 'search_within'. The context implies filtering by park or state, but lacks 'when not to use' or mentions of sibling tools for different needs.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by specifying the output fields (full name, description, designation, states, GPS, address, official URL) and filter options, offering context beyond the annotations without contradiction.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds information. It is efficient without redundancy.

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

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

The description covers the main purpose, filters, and return fields. With an output schema present, it is sufficiently complete. Minimal gaps (e.g., pagination is not mentioned but start and limit parameters exist in schema) do not detract significantly.

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

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

Schema coverage is 100% with parameter descriptions. The description reinforces the parameter usage (e.g., '2-letter, comma-separated' for state, 'parkCode list') and clarifies how filters can be combined, adding practical 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 'List or search NPS parks' and specifies filtering options and return fields, distinguishing it from sibling tools like 'get_park' (single park) and other listing 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 lists filtering options but does not explicitly guide when to use this tool versus alternatives like 'get_park' or other list tools. It implies usage for park listing/search but lacks explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's main behavioral addition is the list of returned fields. This is useful but not extensive, resulting in a neutral score.

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

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

The description is two sentences, front-loading the core purpose and returns, followed by a concise usage tip. Every sentence earns its place 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's simplicity (one optional parameter, no output schema) and comprehensive annotations, the description covers purpose, return structure, and usage guidance adequately. No gaps remain.

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

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

The input schema has 100% description coverage, with the parameter 'include_inactive' already well-described. The tool description does not add any parameter semantics beyond the schema, so baseline score 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 explicitly states 'List the caller's active subscriptions' and enumerates the returned fields (id, type, etc.), making the purpose clear and differentiating it from sibling tools like subscribe and unsubscribe.

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

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

The description provides specific usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't explicitly exclude other contexts, the guidance is clear and actionable.

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

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

Annotations already declare readOnly and idempotent hints. The description adds that the tool returns park service activities and filtering options, but does not add behavioral traits like pagination or rate limits beyond annotations.

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

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

The description is two sentences: first clearly states purpose with examples, second explains filtering. No filler, front-loaded with key information.

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

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

Given the simple parameter set and existence of output schema, the description is mostly complete. It could mention default behavior or pagination, but overall sufficient for a list tool.

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

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

Schema coverage is 100% with each parameter described. The description mentions filtering by parkCode or state, which aligns with schema, but does not add new semantic meaning beyond what is already in the schema.

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

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

The description clearly states the tool lists activities recommended by the park service, with specific examples like hikes and ranger programs. It distinguishes from sibling tools like list_parks and list_alerts.

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

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

The description mentions filtering by parkCode or state, implying when to use, but does not explicitly state when not to use or name alternatives among sibling tools.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context about data lag (6-12 months), keyless access, and the ability to query system-wide totals. This goes beyond what annotations provide, though it could mention rate limits or response structure.

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

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

The description is three concise sentences. The first sentence states purpose, the second gives query examples, and the third details parameters. Every sentence adds value without repetition. It is well front-loaded.

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

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

Despite no output schema, the description mentions returning 'monthly + annual recreation and total visitor counts', giving some output context. It covers input parameters comprehensively. However, it could briefly describe the return format (e.g., JSON structure) to fully compensate for the missing output schema. Given the tool's moderate complexity, this is a minor gap.

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

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

With 100% schema coverage, baseline is 3. The description significantly adds meaning: explains park can be name or 4-letter code, notes year defaults to most recent complete year, describes optional range parameters (start_year, end_year), and clarifies system_total behavior. This helps the agent understand parameter combinations and defaults 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 states a specific verb (answer visitation statistics) and resource (national park visitor counts), with concrete question examples and usage examples. It clearly distinguishes from sibling tools like get_park or list_parks by focusing on visitation 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 clear context for when to use the tool (e.g., 'how many people visited Yellowstone') and includes example inputs. However, it does not explicitly state when not to use it or mention alternative tools for non-visitation queries, which would elevate it to a 5.

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

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

Annotations only provide generic flags (readOnlyHint false, etc.), so the description carries the behavioral disclosure burden. It fully delivers: explains the claim_token flow for anonymous submissions, describes the daily digest and roadmap signal, discloses the 5-per-day rate limit, and clarifies it is free without counting against the tool-call quota.

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

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

Although the description is relatively long, every sentence contributes essential information — purpose, use cases, exclusions, anonymous token flow, rate limit, and fee status. It is front-loaded with the core purpose and organized with conditional guidance, making the length justified.

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

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

In the absence of an output schema, the description partially explains return behavior: anonymous filings yield a claim_token, and passing it back reads resolution status. However, it does not specify what an authenticated filing returns or the exact structure/status payload of the response, leaving a minor but notable gap.

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

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

Schema description coverage is 100% for all four parameters, so the baseline is 3. The description adds some contextual nuance around claim_token usage (e.g., passing it back later), but it does not substantially enhance the meaning of the parameter fields 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the feedback categories (bug, feature/data_gap, praise) and clearly distinguishes this tool from all sibling tools by limiting scope to Pipeworx-served tools.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also provides a concrete decision rule for uncertain cases: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds caching details (5min-1h), data source (CF analytics-engine), and privacy assurance (no PII). No contradictions.

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

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

Two well-structured paragraphs. First sentence front-loads purpose. Every sentence adds value: return values, use cases, caching, and derivation details. No redundant or vague language.

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

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

For a simple read-only trend tool with one optional parameter and no output schema, the description is fully complete. It covers what is returned, how data is aggregated, caching, privacy, and use cases. No gaps.

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

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

Schema covers 100% of parameters. Description adds semantic meaning to the window parameter by explaining that shorter windows surface hot trends and longer windows show steady-state demand, beyond the enum list.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It uses a specific verb ('returns') and resource ('trending data'), and distinguishes from siblings like `discover_tools` or `ask_pipeworx`.

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

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

Lists three explicit use cases and explains window choice (short window for hot trends, long window for steady-state). Lacks explicit exclusions or when-not-to-use guidance, but context is 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?

The description discloses numerous behavioral traits beyond annotations: the two arb-check methods, semantic anchor, partition filter, fill check with live CLOB depth, and response structure. Annotations already indicate read-only and non-destructive, which the description confirms. No contradiction.

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

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

The description is lengthy but well-structured with bold section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though a slightly more concise summary could be beneficial. It front-loads the main purpose and modes.

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 modes, algorithms, edge-case handling), the description is highly complete. It explains input options, internal checks, response fields, and when to avoid trading. Without an output schema, the description substitutes by outlining the expected response structure.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant context: how each mode works, what the parameters accept (slugs, URLs, seed questions), and the underlying logic. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It names specific resources (Polymarket markets, events) and distinguishes itself from related tools like polymarket_fill_risk by explaining its unique capabilities and limitations.

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: no args for trending scan, event mode for a specific market slug, topic mode for cross-event scanning. It also tells when NOT to use (when fill check shows non-realizable edge) and references a sibling tool for custom sizing. However, it does not directly compare to all sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral details: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, fed_candidates, diagnostics), edge computation methods, and impact of knobs. 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 thorough but verbose. It front-loads the main purpose, but then delves into extensive technical details about model families and segments. While well-structured with numbered segments, the length could be reduced by omitting internal implementation details that are unnecessary for tool selection.

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 (9 parameters, no output schema), the description is remarkably complete. It explains response top-level structure, edge computation, knobs, diagnostic outputs, and even caching behavior. All key aspects are covered, enabling an agent to understand what the tool returns and how to configure it appropriately.

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

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

Schema coverage is 100% with each parameter having a description. The description adds context beyond the schema, e.g., explaining 'Tradeable-edge filter' for max_spread_pp and min_liquidity, and elaborating on min_partition_leg_kelly's special behavior. This extra context justifies a score above 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 tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return), resource (Polymarket markets), and distinguishes from sibling tools by its focus on edge detection based on model disagreement.

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" — agents discover opportunities without paging hundreds of markets.' This provides clear usage context. It does not explicitly state when not to use it or compare to siblings, but the segmentation and knob descriptions imply appropriate 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?

The description adds significant behavioral context beyond annotations: it explains the response structure (tracked, expired, snapshot_dates), that data is based on daily closes, that gaps occur on cache-miss days, and that decay is computed from absolute edge values. Annotations already indicate read-only and idempotent, and description reinforces these.

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 and informative but slightly verbose. It front-loads the core purpose and then details response format, which is good. However, it could be tightened slightly without losing clarity.

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

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

Despite having no output schema, the description comprehensively explains the response fields (tracked, expired, snapshot_dates) and their meanings. It also covers limits and data sources, making the tool's behavior fully understandable.

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

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

The description adds meaning to both parameters: clarifies default and max for 'days', and explains 'window' as a snapshot family with examples. This goes beyond the schema's brief descriptions, providing practical guidance.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, using a specific question ('how long has this edge existed and is it shrinking?') that distinguishes it from sibling tools like polymarket_edges, which likely give current edge values.

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

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

The description explains the tool's use case by contrasting a fresh edge with an old one, implying when to use it. It mentions limits (60-day TTL) but does not explicitly state when not to use it or name alternative tools.

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

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

Discloses behavioral traits beyond annotations: walks the ladder, returns verdict (clean/degraded/cannot_fill), explains forced_directional_risk. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all consistent).

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?

Efficiently structured: purpose first, then required modes, then details. Each sentence adds value. No redundancy. Front-loaded with key purpose.

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

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

Complete for complex tool: covers input requirements (two modes), output fields with interpretations (e.g., thin_legs, forced_directional_risk), and use cases. No output schema, but description adequately explains return values.

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 significant meaning: explains side default logic for basket mode, interprets size_usd as settlement notional for baskets, and notes clamp range. Adds value beyond schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes with specific return fields, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why (partial fills, unhedged risk), providing clear context vs. alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses an extraordinary amount of nuance: compatibility_warning and compatibility_codes[] can be non-empty even when matched_pairs>0, temporal_alignment null means "could not be computed" rather than aligned, pairing is keyword-based (pairing_unverified) rather than a shared resolution source, and every spread_pp is gross because Kalshi fees are not modeled. This is model-level transparency for failure modes, null semantics, and caveats.

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 a clear purpose and mode rundown, and nearly every sentence carries real information. However, it is very long for a 3-parameter tool and repeats itself in places — the compatibility codes are enumerated in the SAFETY FIELDS section and then partially repeated as per-entry flags[], and the temporal_alignment_unknown caveat appears twice.

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 carries the full burden of explaining return values, and it does so thoroughly: leg prices, spread[].top_spreads_pp, temporal_alignment structure, fees_note, skipped counters, and low_confidence_pairs are all specified. The only gap is the zero-required-params case — a call with no topic and no explicit pair is never addressed — and there is no minimal example, so a 5 is not warranted.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value by organizing the three parameters into two interaction modes (topic vs explicit ticker) and stating that explicit params override the topic-mapped side while both modes run the identical token-overlap matcher. This clarifies parameter interplay in a way the individual schema entries do not.

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

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

The opening sentence states the resource precisely — "Cross-venue spread between Kalshi and Polymarket for the same resolving question" — and the description makes the behavior unmistakable by defining two modes and the exact output (top_spreads_pp, Kalshi − Polymarket). The definition is specific enough for an agent to separate it from sibling tools like polymarket_arbitrage or polymarket_edges even without explicit sibling naming.

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 clear mode-selection guidance: topic for 10 pre-mapped shortcuts and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, with both modes explicitly said to run the identical matcher. It also manages expectations with "most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable." However, it never references sibling tools or states when to choose an alternative such as polymarket_arbitrage instead.

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, destructiveHint. The description adds value by noting scoping to user identifier and the behavior of omitting the key (listing all). No contradiction with annotations.

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

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

The description is concise (three sentences), front-loaded with the primary action, and each sentence adds meaningful information without waste.

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

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

The description covers both retrieval and listing behaviors. No output schema exists, but the description sufficiently explains functionality. Could mention return format, but acceptable given simplicity and annotations.

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

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

Schema coverage is 100% and the schema property description already conveys the key's use. The description's mention of omitting the key to list all keys is redundant, so it adds little 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 'retrieve a value' or 'list all saved keys', specifying the verb and resource. It distinguishes from siblings 'remember' and 'forget' by defining the complementary role.

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

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

The description explicitly says 'use to look up context... without re-deriving it from scratch' and mentions pairing with remember/forget. It implies when to use but does not provide explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds important behavioral detail: the mark_read parameter flags events as read, affecting subsequent calls, and explains polling suitability. This extends 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?

Concise, well-structured: opens with purpose, details return fields, explains parameters, describes side effects, and notes alternative access. Every sentence adds unique 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?

Despite no output schema, the description explains return fields (source, citation_uri, raw payload) and covers main use cases (filtering, mark_read). Lacks pagination detail for limit but is otherwise comprehensive for a read tool with strong annotations.

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

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

Schema coverage is 100%, but description adds rich context: explains 'type' filters by subscription type, 'since' uses ISO timestamps with fired_at semantics, 'mark_read' and 'unread_only' have clear behavioral effects, and 'limit' defaults to 50. Greatly enhances schema.

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

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

Description clearly states the tool pulls fired events from a subscription feed and returns the most recent alerts. It specifies return fields and distinguishes from siblings like list_alerts by focusing on the persisted feed and mark_read 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?

Explicitly says polls work fine and points to an alternative GET endpoint for scripts/dashboards, giving context on when to use this tool vs. direct access. Lacks explicit when-not guidance but is 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 (readOnlyHint, idempotentHint, etc.) are present. Description adds behavioral context: parallel fan-out to multiple sources, GDELT preferred with GNews fallback, USPTO soft-fail, return structure with citation URIs. No contradiction with annotations.

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

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

Single dense paragraph, front-loaded with example queries, every sentence adds value. No wasted words.

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

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

Given 3 required params, no output schema, and rich annotations, the description covers all behavioral aspects: sources, fallback, return structure, and tool alternatives. No gaps.

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

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

Schema coverage is 100% with descriptions. Description adds examples (ISO date vs relative shorthand, ticker vs CIK) and typical usage hint for 'since'. 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 it provides a 'change feed for a company in the last N days/weeks/months' with specific example queries and sources. It distinguishes from sibling tool 'entity_profile' by saying 'Use entity_profile instead when you want the static profile'.

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

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

Explicitly says when to use this tool vs entity_profile. Provides example queries and explains data sources (SEC, GDELT/GNews, USPTO). Lacks explicit 'when not to use' 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?

The description adds behavioral context beyond annotations: stored as key-value, scoped by identifier, 24-hour retention for anonymous sessions, persistent for authenticated users. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are not contradicted.

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 (4 sentences), front-loaded with the core purpose, and efficiently covers usage, behavior, and pairing with siblings. No redundant or unnecessary information.

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

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

Given no output schema, the description adequately explains what the tool does and its persistence behavior. However, it does not mention return values (e.g., success indicator) or error conditions, which would be helpful for completeness. Still, it is sufficient for an idempotent write tool.

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

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

The input schema provides 100% coverage with descriptions for both parameters (key, value). The description adds value by providing concrete examples for key (subject_property, target_ticker, user_preference) and clarifying that value can be any text, reinforcing schema details.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It lists specific use cases (resolved ticker, target address, user preference, research subject) and distinguishes it from sibling tools like recall and forget.

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

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

The description explicitly advises when to use the tool: 'Use when you discover something worth carrying forward.' It also explains the scope (scoped by identifier) and persistence differences (authenticated users vs anonymous sessions). Additionally, it mentions pairing with recall and forget for retrieval and deletion.

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

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

Discloses rich behavior beyond the readOnly/openWorld/idempotent annotations: graceful degradation when LEI/FIGI enrichment fails, the 'asserts nothing' behavior with ambiguous matches, explicit reporting of unresolved identifiers, internal cascading across endpoints, and source-labelling of identifiers. No contradiction with annotations; this adds substantial context an agent needs to interpret results correctly.

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 examples and the core purpose, then moves into supported types. It is dense but mostly earns its length; a few sentences are overlong and combine multiple clauses (e.g., the figi_candidates explanation), slightly hurting readability. Overall still efficient for the amount of guidance provided.

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 this tool's complexity (multiple identifier types, enrichment, ambiguity, degradation) and lack of an output schema, the description covers the critical aspects: inputs, outputs like `figi_candidates` and `unresolved`, unsupported entity types (non-EDGAR issuers via ISIN), and failure behavior. An agent can confidently decide when and how to call it, and interpret its response.

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

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

Schema already describes both parameters, but the description adds crucial semantics: the distinction between ticker/CIK/name for companies, brand vs generic for drugs, and the 'ENTITY NAME ONLY' rule with a concrete bond example showing why 'revenue bonds' should be stripped. This goes well beyond the schema in preventing incorrect invocations.

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

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

Uses specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It is clearly distinguished from sibling tools by focusing on name-to-ID resolution, with explicit query examples that signal when it applies. The 'Use FIRST whenever you have a name but need an ID' line further cements its unique role.

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 instructs 'Use FIRST whenever you have a name but need an ID' and provides representative utterances ('What's the ticker for…', 'find the CIK for…'), giving an agent clear triggering conditions. It does not name specific sibling tools as alternatives or explicitly state negative cases, but the guidance is strong enough for practical 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?

Annotations declare readOnlyHint, idempotentHint, destructiveHint; description adds that it probes each entity with ai_visibility_check, ranks results, and returns score/confidence/signal density. No contradictions. The description provides useful behavioral context beyond the annotations.

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

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

The description is a single paragraph of 3-4 sentences, front-loaded with the main purpose. Every sentence adds value without repetition 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It describes the internal process (calling ai_visibility_check) and the input contract (2-8 entities, etc.). The tool is complex but the description covers all key aspects.

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 some context (first entity treated as subject, role of context) but does not significantly enhance parameter understanding beyond the 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 uses a specific verb-resource pair 'Compare AI visibility' and clearly distinguishes from sibling tool 'ai_visibility_check' by emphasizing multi-entity side-by-side comparison. It explicitly states what the tool does and its competitive audit use case.

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: for competitive AI-marketing audits, with an example. It contrasts with the single-entity sibling 'ai_visibility_check' by mentioning 'probes each entity... ranks by score'. Lacks an explicit 'when not to use' statement but is otherwise 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?

Adds significant behavioral context beyond annotations: fans out to multiple services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is somewhat lengthy but every sentence carries important information. It is front-loaded with the core purpose and then provides necessary details. Could be slightly more concise but still effective.

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

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

No output schema exists, so the description fully compensates by detailing the return structure (summary block fields, per-advisory details, links, alternative versions) and error handling (sources_failed). Extremely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning (e.g., scoped packages accepted) beyond what the schema already provides. Adequate but not enhanced.

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's a composite check for adding an npm package, aggregating deps.dev and bundlephobia data. It distinguishes itself from siblings by specifying the exact use case and ecosystem scope.

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

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

Explicitly tells when to use it (when asked about safety/popularity/size/cost of an npm package) and when not to (PyPI/Maven etc. use deps.dev directly). Includes caveats about 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?

Adds significant context beyond annotations: truncation at 200K chars, embedding model (BGE-base-en), window size (500-char overlapping), cosine similarity, and offset inclusion. Annotations already declare safety, but description enriches behavioral 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?

Description is concise: two paragraphs, first stating purpose and usage, second technical details. No fluff, every sentence adds information.

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

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

For a tool with 3 params and no output schema, it covers everything: what the tool does, when to use, parameters usage, and expected output (passages with offsets and scores). Truncation and model details are also provided.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing context for 'text' (document text), 'query' (with examples), and 'limit' (default 5, range 1-20). This exceeds the bare 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 action ('Semantic search INSIDE a fetched record'), specifies the resource (a long text like SEC 10-K), and distinguishes from siblings by naming ask_pipeworx_grounded as a complement.

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') and provides a clear pairing with ask_pipeworx_grounded for grounding. No exclusions needed.

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, such as the always-on feed, SMS cap (10/day), webhook auto-disable after 10 failures, and one-time delivery secret. This helps the agent understand side effects and constraints that annotations alone do not capture.

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

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

Well-structured and concise: starts with a clear purpose, then lists requirements, supported types with examples, and delivery options with behavioral notes. Every sentence adds value without verbosity.

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 the return value (subscription ID), delivery channels, and prerequisites, but omits two subscription types from the description, leaving the agent without complete type information. The tool is complex with nested objects, so the description should cover all enum values.

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

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

The description enriches the schema with concrete examples and explanations for the three listed types, but lacks examples for patent_grant and clinical_trial. Since schema coverage is 100%, the omission is noticeable but the description still adds value overall.

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 creates a subscription and returns its ID, but it only lists three of the five supported types (sec_8k, polymarket_edge, fred_series), omitting patent_grant and clinical_trial, which are in the schema. This could mislead the AI agent about the full range of options.

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

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

Provides clear context for when to use (creating proactive monitoring subscriptions) and prerequisites (Pipeworx OAuth account). However, it does not explicitly compare with sibling tools like 'list_subscriptions' or 'unsubscribe', leaving the agent to infer when this tool is the appropriate choice.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and behavior. The description adds value by revealing the output structure (category-bucketed examples with tool+argument shapes) and usage modes (no args vs topic). 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 slightly long but well-structured: starts with alternative phrasings, then explains return, call guidance, and use case. Every sentence serves a purpose, though the list of example topics partially duplicates schema content.

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

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

Given the tool's simplicity (1 optional param, no output schema, high annotation coverage), the description completely covers what it does, how to use it, and when to use it. It provides sufficient context for an agent to invoke correctly.

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

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

The input schema already thoroughly describes the single optional parameter `topic` with enumerated examples. Schema coverage is 100%, so description adds minimal value beyond reinforcing the parameter usage. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it's an onboarding entry point that returns category-bucketed example questions with exact tool/argument shapes. It lists many example topics and explicitly says to use it first when unfamiliar with Pipeworx's capabilities, distinguishing it from siblings like ask_pipeworx or entity_profile.

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

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

Provides explicit guidance: call with no arguments for full spread or pass `topic` to focus. Also states the tool should be used FIRST when you don't know what Pipeworx can do or to learn how to call meta-tools, clearly indicating when to use.

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

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

The description adds behavioral context beyond annotations: deactivation (not deletion), ownership enforcement, and historical availability. No contradictions with annotations.

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

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

Two concise sentences with no wasted words, front-loading the primary action.

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

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

For a simple tool with one parameter and no output schema, the description covers usage constraints and side effects sufficiently. Could mention return value but not necessary.

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

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

Schema covers 100% of parameters; description does not add extra meaning beyond the schema's parameter 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 uses specific verb 'cancel' and resource 'subscription by id', clearly distinguishing from sibling tools like subscribe and list_subscriptions.

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

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

Ownership enforcement is stated ('you can only cancel your own subscriptions'), providing context for when this tool is appropriate. However, no explicit alternatives or when-not-to-use guidance is given.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the full set of verdicts, the meaning of 'could_not_verify' (check did not happen) versus 'unsupported' (no source exists), and that citations use pipeworx://. This is significant behavioral context about failure modes and return semantics.

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 information-dense; every sentence contributes operational guidance, and the structure flows logically from purpose to usage to return semantics to warnings. It is slightly verbose but not padded or redundant.

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 enumerates the possible verdicts, the payload (grounded or structured actual value with citation), and the error object with stage/detail. It also explains how this tool replaces multi-step workflows, making it exceptionally complete for callers.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on tolerance_pct (override behavior, recommended range for hallucination detection) and giving concrete claim examples for the 'claim' parameter, which enriches the schema's minimal 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 uses specific verbs like 'verify' and 'fact check' and names the resource as natural-language claims. It clearly distinguishes this tool from siblings by describing the two-pipeline behavior (SEC EDGAR/XBRL for company financial claims, grounded pipeline for everything else) and by stating it replaces 4–6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides detailed routing rules (financial vs. other) and instructs callers on how to interpret 'could_not_verify' and 'unsupported,' which is essential for correct usage.

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