Jwt

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the return format (per-model score, confidence, signals, raw_response plus combined view) and explaining the API key pass-through behavior for Anthropic calls.

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 tight three-sentence paragraph that front-loads the purpose, then covers usage and return format. Every sentence provides essential information 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?

Given no output schema, the description sufficiently explains the return structure and key parameters. It covers purpose, usage, and behavioral details. Minor omissions like error handling or rate limits are not critical given the openWorldHint and idempotent nature.

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

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

Schema coverage is 100%, so each parameter is already described. The description adds useful context: default model for 'models' omission, explanation of '_apiKey' as pass-through to Anthropic, and role of 'context' for disambiguation. This enhances understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the action, resource, and output, distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring rather than general presence scanning.

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 default model and optional Anthropic probing with BYO key, giving clear usage context. It also suggests use cases (AI-marketing audits, pre-launch checks, competitive monitoring). However, it does not explicitly state when not to use this tool or mention alternative tools for similar tasks.

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 non-destructive. The description adds useful context: returns structured answer with pipeworx:// citation URIs, is a single fast call, and works on every tier. 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 relatively long but well-structured with a clear headline, examples, and differentiation from siblings. Every sentence adds value and earns its place, though it could be tightened slightly.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, usage, examples, and behavioral context comprehensively. It lacks mention of rate limits or cost, but overall is complete for agent decision-making.

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

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

Schema coverage is 100% and the description doesn't add significant meaning beyond the schema for parameters. It provides examples and mentions aliases, but the schema already explains the 'question' parameter.

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

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

The description clearly states the tool's function: routing questions to 4,552 tools across 1,160 sources for authoritative structured data with citations. It distinguishes itself from web search and siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH', specifies when to use (factual questions with examples), and when to step up to ask_pipeworx_grounded or deep_research. States 'START HERE for most questions'.

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 detailed behavior beyond annotations: returns a specific structure with evidence, explicit refusal reasons, and mentions the extra LLM call. Annotations already declare read-only and idempotent, but description adds valuable context.

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

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

The description is relatively long but well-structured and front-loaded with the core purpose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given the tool's complexity (high-stakes, grounded answer) and lack of output schema, the description compensates by detailing return format and refusal reasons. It also explains the mechanism and differentiates from siblings.

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 parameter-level detail, but the parameters are aliases for 'question' and are self-explanatory in the schema. No additional semantic value from description.

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

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

The description clearly states the tool's function: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb 'extract' and the resource (tool result), and distinguishes it from the sibling 'ask_pipeworx' by highlighting the grounded extraction and extra cost.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and provides alternatives: 'prefer ask_pipeworx for casual lookups.' It also notes the cost trade-off.

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 mark it as readOnly, idempotent, non-destructive. Description adds extensive behavioral context: status short-circuits, resolution-rule risk, fan-out behavior, and tradeability warnings, going well 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 very long and dense, packed with examples, edge cases, and details. While each sentence adds value, the length may overwhelm agents. Could be more front-loaded and structured for quick parsing.

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

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

Despite no output schema, the description thoroughly documents return shapes (market, analysis, evidence, parent_event, match confidence), blocking conditions, and edge cases. Covers all essential information for agent invocation.

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

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

Schema coverage is 100%, yet the description enriches each parameter: market parameter explains three input types, depth encodes fan-out scope, include_raw details the summary-vs-raw tradeoff. Adds meaning beyond schema definitions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, question) and distinguishes from sibling tools like polymarket_edges by emphasizing evidence gathering and market-model comparison.

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

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

Provides explicit use cases ('should I bet on X') and examples of when to use. Describes blocking conditions (low-confidence matches, closed markets) but lacks direct comparison to 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 the tool is read-only, idempotent, and non-destructive. The description adds substantial detail: for companies, it pulls specific financials from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, it pulls FAERS counts, FDA approvals, and trial counts. It also mentions sorting by primary metric and returning citation URIs, all 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 somewhat long but every sentence adds value. It is front-loaded with example queries, which is helpful. Could be slightly more concise, but overall efficient.

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

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

Given no output schema, the description covers return format (paired data + citation URIs), data sources, and the algorithm (sorted by primary metric). This, combined with annotations, provides complete context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds examples for both parameter values: for company, tickers/CIKs like AAPL, MSFT; for drug, names like ozempic. This clarifies format and acceptable inputs beyond the schema's description.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. Example queries like 'X vs Y' and 'rank these companies' make the purpose immediately clear. It distinguishes itself from sequential single-pack lookups, which are sibling tools 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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong usage directive. Context for each type (company vs drug) is given with specific data sources, guiding when to use each.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds key details: keyless, offline, and the critical limitation of no signature verification. No contradiction.

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

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

Two sentences, no extraneous information. Key points front-loaded. Every word earns its place.

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

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

Single parameter, simple tool. Output is described sufficiently. No missing context for an agent to use the tool correctly.

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

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

Parameter 'token' has full schema coverage (100%). Description does not add beyond the schema's definition. Baseline 3 applies.

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

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

Description clearly states it decodes a JWT keyless/offline, returning header, payload, and standard claims summary. Distinguishes from signature verification, which is a common sibling task.

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

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

Explicitly warns that it does not verify the signature, establishing when to use (decode) and when not to (verify). No alternative mentioned but the note 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 provides detailed behavioral transparency beyond annotations, including account requirements, parallel execution across 4,552 tools, expected response time (15-60s), the structure of the findings packet (evidence, confidence, source, citation, gaps), and limitations (empty gaps for non-structured topics). Annotations only indicate read/write/idempotent/destructive hints, which the description expands upon significantly. (Evidence: 'ACCOUNT REQUIRED... depth:"thorough" needs a paid plan... Decomposes your question into focused facets, routes each to the right one of 4,552 tools IN PARALLEL... returns a findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]... Expect 15-60s.')

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 comprehensive, front-loading critical operational details (account requirement, alternative tool) before explaining the tool's mechanism. Each sentence contributes necessary information for proper agent selection and invocation. Minor deduction for density; could be slightly more structured, but overall well-organized. (Evidence: 'ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx... Grounded multi-source research...' etc.)

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 thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps), expected response time (15-60s), and limitations (empty gaps for non-structured topics). Together with annotations (readOnly, idempotent), it provides sufficient context for understanding the tool's behavior and risks. (Evidence: description explains the output structure and limitations.)

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by clarifying that the 'thorough' depth requires a paid plan, which is not specified in the schema, and reinforces that the question is decomposed into facets. This extra context justifies a score of 4. (Evidence: 'depth:"thorough" needs a paid plan' and context about decomposition.)

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: conducting broad, multi-part research over 1160 structured data sources, decomposing questions into facets and returning a packet with citations and gaps. It distinguishes itself from ask_pipeworx and mentions when to use each. (Evidence: 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources... Decomposes your question into focused facets... returns a findings packet... Best for broad/multi-part questions over structured 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 usage guidelines: when to use deep_research (broad/multi-part structured data questions), when to use ask_pipeworx (single lookup, breaking news, colloquial current news), and prerequisites (account required, paid plan for thorough depth). Also notes that if not signed in, use ask_pipeworx instead. (Evidence: 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx... If you are not signed in, use ask_pipeworx 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 mark the tool as read-only and idempotent. The description adds behavioral context: it returns top-N relevant tools with full schemas and curated examples, ready to call directly without further lookup. This goes beyond annotations to clarify the tool's output and usage pattern.

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

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

The description is concise and front-loaded: first sentence states purpose, then lists use cases, return format, and usage advice. Every sentence adds meaningful information, and the structure is logical 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?

The description covers the main return value (tools with names, descriptions, schemas, examples) and addresses the ready-to-call nature. However, it does not detail pagination or the default limit (schema says default 20), which could be useful for agents making multiple calls. Overall, it is sufficiently complete for a discovery tool given the annotations and schema.

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

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

Schema coverage is 100% with each parameter described. The description adds value by explaining that q, task, search, and description are aliases for query, and provides example queries. This structure helps the agent understand parameter flexibility beyond what the schema alone conveys.

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 provides a comprehensive list of data domains (SEC filings, financials, etc.) and differentiates itself from siblings by urging to 'Call this FIRST when you have many tools available,' indicating its role as an exploration tool rather than a task-specific one.

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 specifies when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by specific data types. It also advises to call it first when many tools are available. While it doesn't include explicit when-not-to-use scenarios, 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?

Adds significant behavioral context beyond annotations: fans across multiple sources, returns specific data, patent soft-fail, parallel call. Contradicts none.

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?

Dense but well-structured with examples and bullet points. Front-loaded with queries. Slight verbosity but earned.

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?

Very complete for a complex tool: explains return fields, sources, caveats, and no output schema is present but description compensates fully.

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

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

Schema coverage is 100%; description adds examples and clarification that names are not supported, but baseline is 3. Extra nuance justifies 4.

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

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

Description clearly states purpose: full cross-source profile of US public company, with many example queries. Distinguishes itself from siblings by explicitly preferring over chaining individual lookups for holistic views.

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 (holistic view queries) and when not (if only a name, use resolve_entity first). Also notes preferred over chaining, providing clear alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds no new behavioral traits beyond the purpose, which is consistent. No contradiction.

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

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

Two sentences, no fluff. Front-loaded with purpose, then usage context. Every sentence adds value.

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

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

For a simple destructive tool with one required parameter and no output schema, the description covers purpose and usage adequately. Could mention error handling for missing keys, but not required 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 a clear description for the single 'key' parameter. Description does not add further meaning beyond the schema's own documentation.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes 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?

Provides explicit guidance on when to use: when context is stale, task done, or clearing sensitive data. Also mentions pairing with 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 (readOnlyHint, idempotentHint, destructiveHint) are already present, and the description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. No contradiction; description enhances understanding.

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

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

The description is a single paragraph of three sentences, front-loaded with the main purpose. Every sentence provides unique information without fluff, earning its place.

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

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

The description covers purpose, input, output format, and use cases. It lacks mention of potential limitations (e.g., rate limits, page size constraints), but given the rich annotations and schema, it is almost complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value beyond schema by stating defaults and limits (e.g., 'default 25, max 50' for max_links) and providing a URL format example.

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 'Generate' and resource 'llms.txt file for any URL'. It clearly distinguishes from sibling tools by stating the exact output and use cases, such as 'getting a client's site indexed by AI'.

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

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

The description lists three explicit use scenarios (client indexing, own project drafting, competitor auditing), providing clear context for when to use the tool. However, it does not mention when not to use it or specify alternatives, so it's not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing return fields, which goes beyond the annotations to inform the agent about the output.

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-loads the core purpose, and avoids extraneous information, making it efficient and easy to parse.

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

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

For a simple list tool with one optional parameter, the description is complete: it defines the action, return fields, and usage context. No output schema exists, but the description adequately covers 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 the parameter 'include_inactive' is well-described in the schema. The description does not add additional parameter information, so baseline 3 is appropriate.

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

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

The description clearly states the action ('List the caller's active subscriptions'), the resource ('subscriptions'), and specifies the returned fields. It effectively distinguishes 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?

Explicitly advises using the tool to review existing subscriptions before adding more or to find an id for cancellation, providing clear context for when to use it and implying 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 are none for safety hints, but the description adds valuable behavioral context: rate-limited to 5 per identifier per day, does not count against tool-call quota, and feedback affects roadmap. No contradictions with annotations.

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

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

The description is two sentences with no fluff. It front-loads the purpose, then provides usage guidelines, behavioral notes, and constraints. Every sentence is essential 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?

Given the tool's simplicity (3 params, one nested, no output schema), the description is complete. It covers purpose, usage, behavior, and parameter guidance. No additional information is needed for correct invocation.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds extra guidance on how to write the message (specific, tool name, error), which adds value beyond the schema. Minor deduction because the schema already covers enum descriptions.

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

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

The description clearly states the tool's purpose: to send feedback (bug, feature, data_gap, praise) to the Pipeworx team. It specifies what each feedback type means and what not to include (end-user prompt). It distinguishes itself from siblings by being the only feedback channel.

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

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

The description explicitly tells when to use the tool (wrong data, missing tool, working well) and what to avoid (pasting end-user prompts). It also mentions rate limits (5 per identifier per day) and that it's free, providing clear context for usage.

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

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

The description discloses the data source (CF analytics-engine), confirms no PII, and mentions caching behavior (5min-1h). This adds valuable context beyond the annotations which already declare read-only and idempotent hints.

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 paragraphs: first states what it does, second lists use cases and technical details. Every sentence adds value, 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?

For a simple read-only tool with one optional parameter, the description provides all necessary context: output structure (top tools, packs, volume), data origin, caching, and use cases. No output schema 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 enum and description. The description adds semantic guidance on how different windows serve different purposes (hot vs steady-state), going beyond the schema's basic description.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume within a specified window, distinguishing it from sibling tools that focus on other aspects like asking questions or discovering 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 lists three specific use cases and explains the difference between window choices, providing clear context for when to use this tool. It lacks explicit exclusions or alternatives, but the context is sufficient.

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

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

Adds extensive behavioral context beyond annotations: describes internal checks (monotonicity, partition_check, semantic anchor, partition filter, fill_check), conditions like skipped_low_similarity and placeholder fraction, and warns about thin legs. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Dense but well-structured: starts with overall purpose, breaks into modes, uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though length is appropriate for the complexity.

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

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

Completely covers input options, algorithmic steps, filtering, output structure (opportunities[], partition_check, fill_check), and edge cases (placeholders, low similarity). No output schema, so description provides that. References sibling tool for additional functionality.

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 provides basic parameter descriptions, but the description adds significant value: explains mode selection, examples, internal processes, and output structure. With 100% schema coverage, baseline is 3; the extra context merits a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) with examples, and distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes exclusion criteria: 'do not trade it' if realizable_edge_pp ≤ 0, and references sibling tool for custom sizing.

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=true, idempotentHint=true, destructiveHint=false) are fully consistent with the description. The description adds significant behavioral transparency beyond annotations: it explains caching (1h at KV level keyed on knobs), response structure including diagnostics (_diagnostics with funnel counters and filter_skips), and edge case handling like placeholder-slug filtering and Fed bet exclusion. No contradictions found.

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

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

The description is a single dense paragraph that covers extensive detail, but it sacrifices conciseness. While front-loaded with the core purpose, the subsequent enumeration of model families, filter behavior, and response fields is verbose and could be streamlined with bullet points or clearer structure.

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

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

Given the complexity (9 parameters, no output schema, three model families), the description is remarkably complete. It explains caching, response top-level, diagnostics, filter behavior, and even provides context on Fed bets and unreliability of signals. This ensures an agent can fully understand the tool's capabilities and limitations without external documentation.

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

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

Schema coverage is 100% with each parameter already described, but the tool description adds substantial semantic value by explaining how parameters function as 'tradeable-edge knobs' and filtering mechanisms (e.g., max_spread_pp for tight books, min_partition_leg_kelly for filtering thin partitions). This context, combined with the existing schema descriptions, makes parameter meaning exceptionally clear.

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: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly targeting the 'what should I bet on today' use case. It also differentiates from potential siblings by detailing three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and their subcomponents, making the tool's specific function unambiguous.

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

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

The description provides strong usage guidance, including the primary use case ('what should I bet on today'), filtering knobs (e.g., min_liquidity, max_spread_pp), and note on Fed bets being excluded. However, it lacks explicit when-not-to-use instructions or direct comparisons to sibling tools like polymarket_arbitrage, though the detailed behavior implies differentiation.

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 fully aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details behavior beyond annotations: response structure (tracked, expired, snapshot_dates), data freshness (snapshots written on cache miss), and limitations (60-day TTL, not intraday). No contradictions.

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

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

The description is a single paragraph that efficiently covers purpose, response details, and limitations. While lengthy, every sentence adds value. The structure is logical: starts with core function, then describes output, then constraints. Minor redundancy in response details but overall concise for the complexity.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and key computed fields (trend, decay_pp_per_day). It covers parameters, limits, and underlying data generation. The complexity of edge persistence analysis is fully addressed, leaving no major gaps.

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

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

Input schema covers both parameters with descriptions, providing 100% coverage. The description adds context by explaining 'days' as lookback with defaults and max, and 'window' as snapshot family with examples. It also clarifies the meaning of the response fields, which helps interpret parameter effects.

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 as providing edge persistence and decay telemetry from daily snapshots, distinguishing fresh edges from older ones. It explicitly answers the question 'how long has this edge existed and is it shrinking?' and differentiates itself from sibling tools like polymarket_edges which likely provide raw edge data.

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

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

The description explicitly advises when to use this tool versus alternatives by contrasting a fresh wide edge with a 3-week-old wide edge, implying the latter is less reliable. It also provides limits on history depth (60-day TTL) and notes that decay numbers come from daily closes, not intraday, guiding appropriate 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?

Description adds behavioral context beyond annotations: requires one of market or event, walks the ladder, returns fields like slippage_pp, verdict, thin_legs, and forced_directional_risk. Aligns with readOnlyHint, idempotentHint, and non-destructive nature.

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 paragraph is dense but front-loaded with purpose. Uses capitalization for key terms. Could benefit from clear section breaks for modes, but every sentence adds necessary detail 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?

Given no output schema, description fully lists return fields for both modes, explains basket risks (thin_legs, directional risk), and gives usage threshold. Covers all needed information for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, but description enhances each parameter with usage context: clarifies size_usd meaning for buys vs sells and basket mode, notes default and clamp range, and explains side auto-detection for baskets. Adds value beyond schema names.

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 checks realizable vs theoretical edge using live order book depth, distinguishing single-market and basket modes with specific inputs and outputs. It differentiates from siblings like polymarket_arbitrage by focusing on risk assessment before acting on arbitrage signals.

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

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

Explicitly states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. Provides reasoning about thin books and partial fills converting arbitrage into directional risk.

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 extensive behavioral context beyond annotations, including safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), detailed explanations of when spreads are meaningful, and counters for dropped comparisons. It fully discloses limitations and edge cases.

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 detailed and front-loaded with the core purpose, then logically explains modes, response fields, and safety fields. While lengthy, every sentence adds value; slight reduction could improve conciseness without losing information.

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

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

Given the tool has no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety warnings, temporal alignment, skipped counters) and how to interpret results. It provides complete context for an AI agent to use the tool effectively.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the purpose of each parameter: topic lists the 10 shortcuts, and kalshi_event_ticker/polymarket_event_slug are described as overrides for custom pairings. Examples in schema further clarify usage.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, with two distinct modes (topic shortcuts and explicit tickers). It is specific and distinguishes from siblings like polymarket_arbitrage.

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

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

The description explains when to use each mode (topic for pre-mapped macro shortcuts, explicit tickers for custom pairings) and warns that most pre-mapped topics return compatibility warnings, indicating poor tradeability. However, it does not explicitly compare against sibling tools like polymarket_arbitrage.

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

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

Annotations already indicate readOnly and idempotent; description adds scoping detail (to user identifier) and pairing instructions, consistent with annotations.

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

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

Three sentences that are front-loaded with action, no verbose or redundant information, each sentence adds value.

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

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

Tool is simple with one optional parameter; description covers basic retrieval and listing behavior, though output format is not detailed (no output schema).

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

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

Schema has 100% coverage with parameter description; description adds clarity that omitting key lists all keys, enhancing semantic understanding.

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

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

The description clearly states the tool retrieves a saved value by key or lists all keys when omitted, with specific verbs and resource distinction from siblings like remember and forget.

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

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

The description explains when to use (look up stored context) and mentions pairing with remember/forget, but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint all positive except destructive=false. The description adds behavioral context beyond this: it explains that setting mark_read:true flags events as read so subsequent calls show only newer ones, and that polls work fine. This enriches the agent's understanding without contradicting annotations.

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

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

The description is highly concise: three sentences covering purpose, return data, filtering, and mark_read effect. No wasted words, and the most critical information (what it does) appears first. It earns every sentence.

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

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

Given the tool has 5 parameters, no output schema, and moderate complexity, the description provides adequate completeness: it explains the core return fields, filtering options, mark_read side effect, and even an alternative HTTP endpoint. It does not detail pagination or limit behavior, but the schema already documents that. The description is rich enough for effective use.

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 giving an example for type ('sec_8k') and explaining the effect of mark_read ('so the next call only shows newer ones'), which goes beyond the schema's generic descriptions. However, it does not cover all parameters (e.g., limit, unread_only) in the description text.

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: 'Pull fired events from your subscription feed.' It specifies the return data (source, citation_uri, payload) and distinguishes itself from siblings by noting it is the feed, with an alternative HTTP endpoint for scripts. The verb 'Pull' combined with 'recent alerts' makes action and resource explicit.

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

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

The description provides clear usage guidance: filtering by type and since, setting mark_read to manage read state, and that polls work fine. It does not explicitly exclude alternatives or compare to sibling tools, but the context is sufficient for an agent to decide when to use it (e.g., retrieving recent alerts from the feed).

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 substantial behavioral details beyond annotations: fans out to multiple sources, fallback logic, USPTO soft-fail, return structure (grouped changes, total count, 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?

Packed with information and front-loaded with examples, but could be slightly more structured (e.g., bullet points). Every sentence adds value.

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

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

Given complexity (multiple sources, fallback, time syntax, grouping), the description fully covers usage, parameters, behavior, and output structure. No output schema but return structure is described.

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

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

Schema coverage is 100%, and description adds meaning: explains accepted formats for since (ISO date or relative shorthand with examples), value as ticker or CIK, and a usage hint for typical monitoring.

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 companies covering SEC filings, news, and patents, with example queries like "what's new with X". It distinguishes from sibling 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 tells when to use (for recent changes queries) and when to use entity_profile instead. Also explains fallback behavior (GDELT preferred, GNews fallback) and soft-fail for USPTO.

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

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

Adds behavioral details beyond annotations: scoped by identifier, persistence times (24 hours for anonymous, persistent for authenticated). No contradiction with idempotentHint, destructiveHint.

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

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

Three tightly-written sentences with zero redundancy. Front-loads the core purpose, then adds usage guidance and behavioral details efficiently.

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 two-parameter schema and no output schema, the description fully covers purpose, usage, behavior, and lifecycle. 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 descriptions cover 100% of parameters with example formats. The description adds examples ('subject_property', 'target_ticker') but does not significantly extend meaning beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations and sessions, using key-value pairs. It distinguishes itself from siblings 'recall' and 'forget' by mentioning them.

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

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

Explicitly advises using the tool 'when you discover something worth carrying forward' and pairs with recall and forget. Also provides context on session vs persistent memory.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds that each call cascades through several internal lookup endpoints, replacing 2-3 manual lookups. It also details what each type returns (company: ticker, CIK, company name, citation URI; drug: RxCUI, ingredient, brand, citation). No contradictions with annotations.

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

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

The description is well-structured with a bulleted list of supported types. It front-loads example queries and concludes with a benefit statement. While slightly verbose, every sentence adds value, maintaining good conciseness for the level of detail.

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

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

With no output schema, the description compensates by fully explaining return values for each entity type, including citation URIs. It covers purpose, usage, behavior, and output, making the tool self-contained and easy to use.

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

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

The schema already covers both parameters fully (100% coverage). The description reinforces with example values (AAPL, ozempic) and disambiguation notes (auto-disambiguated for company name), adding useful illustrative context beyond the schema.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers, listing specific examples like ticker, CIK, and RxCUI. It uses a specific verb ('resolve') and resource ('entity'), and implicitly distinguishes from siblings by positioning itself as the first step when needing an ID.

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 FIRST whenever you have a name but need an ID' and provides example queries. It does not explicitly exclude alternatives, but the context makes it clear that this tool is for ID resolution, not for tasks like profiling (covered by sibling entity_profile).

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check per entity, and that context disambiguates common names. Provides useful behavioral detail beyond annotations.

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

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

Two sentences (23 words) with front-loaded purpose. Every sentence adds value; no filler. Perfectly 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?

Despite no output schema, description explains return format (ranked list with score, confidence, signal density). Covers purpose, usage, internal mechanism, parameter nuances. Fully complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. Description adds critical semantic: first entity is treated as 'subject' for narrative, rest as competitors. Also explains model default and API key requirement. Significantly enhances understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes and ranking. It distinguishes from sibling ai_visibility_check which handles single 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?

Explicitly states usefulness for competitive AI-marketing audits and gives an example. Implies when not to use (single entity) by referencing ai_visibility_check, but lacks explicit 'when not to use' statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts, and details the return structure. 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?

Single, well-structured sentence that front-loads the core purpose and packs essential details (sources, use cases, ecosystem scope, fallback, return info) 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?

Despite no output schema, the description thoroughly covers the composite nature, what is checked, return summary, partial failure handling, and ecosystem limitations, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with parameter descriptions. Description adds extra detail: scoped packages like '@types/node' are accepted, and provides context for version defaults and scoping.

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 npm package evaluation across deps.dev and bundlephobia, with a specific verb+resource ('scan dependency') and distinguishes itself by being a one-call multi-source tool.

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

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

Explicitly says when to use (queries about safety, popularity, size, cost of adding a package) and when not to use (other ecosystems like PyPI, Maven, Cargo, Go, which fall under deps.dev:version directly). Provides clear 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?

Discloses technical details beyond annotations: uses BGE-base-en embeddings with cosine similarity, 500-char overlapping windows, and a 200K character cap with truncation flagging. This provides rich behavioral context. No contradictions with annotations (all readOnly, idempotent, openWorld).

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?

A single well-structured paragraph that front-loads the main purpose, then adds usage context, technical details, and limitations. Every sentence is informative and earns its place.

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

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

Given no output schema, the description completely describes the return value (top-N passages with offsets and similarity scores) and the underlying mechanics. It is fully adequate for an agent to understand and invoke 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 baseline is 3. The description adds value by providing natural-language query examples and explaining the truncation behavior for the text parameter, exceeding basic schema documentation.

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

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

The description clearly states the tool does 'Semantic search INSIDE a fetched record' with specific verbs and resource. It distinguishes usage context by explaining when to use (record too big) and pairs with a sibling tool (ask_pipeworx_grounded).

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 concrete alternative strategy: 'fetch with the gateway, ground over the relevant passages'. This gives clear guidance on tool 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?

Beyond annotations, the description discloses crucial behavioral traits: auth requirements, that the feed is always on, optional email/SMS/webhook with specific constraints (phone verification, daily cap, auto-disable after 10 failures), and one-time webhook signing secret. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It is relatively long but every sentence adds value, covering prerequisites, types, and delivery details. Minor room for improvement: could be slightly more concise, but overall efficient.

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

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

Given the tool's complexity (nested parameters, multiple types and channels, constraints), the description is highly complete. It covers purpose, return value, auth, detailed type parameters, delivery channels, and operational behaviors. Missing only some implicit info like idempotency (covered by annotations) and unsubscribe reference, but overall excellent.

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

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

The description adds substantial meaning beyond the input schema, providing detailed examples for each subscription type (e.g., sec_8k with ticker and items) and explaining delivery subfields with operational constraints (e.g., phone must match verified account, webhook auto-disable). Schema coverage is 100%, but the description goes far beyond the basic schema descriptions.

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

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

The description clearly states the verb 'create' and the resource 'proactive monitoring subscription to a live-data event stream', and explicitly mentions it returns a new subscription ID. It differentiates from sibling tools like list_subscriptions and unsubscribe, which manage existing 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?

The description provides context for usage, including the requirement for a Pipeworx OAuth account and detailed explanations of subscription types and delivery channels with constraints. However, it does not explicitly instruct when to avoid using this tool in favor of alternatives, though the creation vs. management distinction 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?

Beyond annotations, the description details the output structure (category-bucketed example questions with tool+argument shapes) and that it draws from a live catalog. 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?

Well-structured with a clear lead-in, purpose, output details, and usage guidance. Every sentence is informative, no fluff.

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

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

Fully covers all necessary information for correct tool invocation: purpose, usage, parameters, output, and relationship to other tools. No gaps given the tool's simplicity.

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

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

The description adds significant value over the schema by explaining the effect of omitting vs. specifying the topic parameter, and listing example topic values.

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

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

Clearly defines the tool as an onboarding entry point that suggests questions. Distinguishes from sibling tools by stating it's the first tool to use when unsure of Pipeworx capabilities.

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 FIRST when you do not yet know what Pipeworx can do') and how to call (no args or with a topic). Provides clear context for usage.

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

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

Description adds valuable behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' 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?

Two sentences, front-loaded with action, no unnecessary words. Highly concise and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and behavioral details. Complete for selection and invocation.

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

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

Schema coverage is 100% with clear parameter description. Description adds minimal extra meaning (source from subscribe), but 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?

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions', providing clear context on when to use. No explicit alternatives mentioned, but the constraint is sufficient.

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

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

The description extensively details behavioral traits beyond annotations: it returns specific verdict types, extracted structured form, actual value with citation, and percent delta. It discloses the underlying sources (SEC EDGAR + XBRL) and notes that it replaces 4-6 sequential calls, providing context on efficiency and scope. 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 well-structured, starting with user-facing examples, then stating purpose, scope, return values, and comparative efficiency. Every sentence adds value, though it could be slightly more concise. It is front-loaded with the most critical information.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers the domain (US public company financial claims), underlying technology (SEC EDGAR + XBRL), return information (verdict types, citation, delta), and its efficiency advantage. This is fully adequate for an agent to understand how to use the tool.

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

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

Although the input schema already describes the 'claim' parameter, the tool description adds substantial meaning: it provides example claim formats, clarifies the accepted domain (financial claims for public US companies), and explains what the output contains. This significantly helps the agent construct appropriate parameter values.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It uses clear verbs ('validate claim', 'fact check') and specifies the resource (SEC EDGAR + XBRL). The scope is well-defined, distinguishing it from general fact-checking 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 clearly indicates when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implies limitations by noting v1 supports only company-financial claims, guiding appropriate use. However, it does not explicitly mention alternatives or when not to use.

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