Pombase

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds transparency by detailing the probing behavior, output format (per-model {score, confidence, signals, raw_response} + combined view), and that using Anthropic requires a user-provided key. 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 two sentences, front-loaded with the core purpose and example, and the second sentence adds key details. Every part is information-dense with no waste.

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

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

Given 4 parameters and no output schema, the description covers return structure and use cases. It explains the scoring output, model options, and optional context. It is fully adequate for an agent to understand 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?

Despite 100% schema coverage, the description enriches each parameter: explains 'entity' with examples, 'models' options and default, '_apiKey' necessity and format, and 'context' for disambiguation. It adds practical value beyond the schema.

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

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

The description uses a specific verb 'Probe' and resource 'LLMs for what they know about a business / brand / product / topic' and explains the scoring output. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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

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

The description states when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model vs. optional Anthropic probe with a BYOK key. It does not explicitly list when not to use or alternatives, but provides sufficient context.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable context: it routes to 3,745 tools across 884 sources, fills arguments, and returns structured answers with stable citation URIs. This 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 a single paragraph that front-loads the key directive 'PREFER OVER WEB SEARCH' and provides comprehensive context. While it is long, every sentence serves a purpose (listing domains, query phrases, examples). A slight trim 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?

Despite no output schema, the description explains the return format (structured answer with citation URIs) and the underlying mechanism (routing to tools). It covers typical use cases thoroughly with examples, leaving no major gaps for the agent to understand its function.

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 multiple aliases for the question parameter, well-documented in the schema. The description adds examples but does not add semantic depth beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to verified sources. It distinguishes itself from web search and other tools with explicit 'PREFER OVER WEB SEARCH' and lists specific domains like SEC filings, FDA data, etc. The verb 'ask' and resource 'pipeworx' are specific.

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

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

The description provides explicit when-to-use guidance: for factual questions about real-world entities, events, numbers, and when user asks phrases like 'what is', 'look up', 'find', etc. It also includes examples and contrasts with web search, though it doesn't list when not to use, it's implied for subjective or non-factual queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: one extra LLM call, refusal scenarios (with explicit reasons), and return structure. 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 dense but efficient, front-loading the critical distinction and usage. All information earns its place, though the density slightly reduces readability.

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,745 sources, 884 sources), sibling tools, and no output schema, the description is remarkably complete: explains output structure, refusal reasons, cost trade-off, and secure data handling.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add individual parameter meaning beyond aliases already in schema. No further semantic enrichment.

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

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

The description explicitly states it is a hallucination-resistant answer mode for high-stakes reads, details the process (same routing as ask_pipeworz, extracts answer only from tool result), and specifies output fields. It clearly distinguishes from ask_pipeworz.

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 tells exactly when to use ('when answer quoted/cited/acted on, must not invent facts') and when to prefer ask_pipeworz ('casual lookups'), providing explicit alternatives and context.

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

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

Annotations indicate safe, idempotent, read-only behavior. The description extensively discloses behavioral traits: low-confidence resolution short-circuiting, closed/dead market handling, wide-spread market warnings, cancellation rule parsing, parent_event extraction, and news fallback fields. This goes far beyond what annotations provide.

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

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

The description is very long and contains extensive detail, including classifiers, fan-out examples, response shapes, and edge cases. While well-structured with sections, it could be more concise. The front-loading of the core purpose helps, but overall verbosity reduces 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 and lack of output schema, the description is remarkably complete. It covers input formats, resolution logic, response fields (market match confidence, evidence, parent events, news fallback), safety mechanisms, and cancellation rules. No gaps are apparent.

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

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

Schema description coverage is 100%. The tool description adds value by explaining how 'market' accepts slugs, URLs, or question text, and gives examples for 'depth' and 'include_raw'. It clarifies when to use each parameter, such as 'include_raw: true' for full payloads.

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 a Polymarket bet by pulling Pipeworx data, using a specific verb-resource pair. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by offering comprehensive research. Examples and classifiers further clarify 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?

Explicit usage contexts are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also details when each classifier is appropriate. While no direct 'when-not-to-use' is stated, the usage 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses detailed behavior: for company type, it pulls latest 10-K financials with correct fiscal year handling; for drug type, it pulls FAERS, FDA approval, and trial counts. It also states results are sorted by primary metric and returns pipeworx:// citation URIs.

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 well-structured, starting with example queries and then explaining functionality. While every sentence adds value, it is slightly verbose; however, it remains efficient for the information conveyed.

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 only 2 parameters with full schema coverage and rich annotations, the description provides complete context: it covers use cases, data sources, sorting, output format (citation URIs), and even mentions that it replaces 8–15 sequential lookups. No output schema is needed as the description sufficiently describes the return.

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 significant value: it explains the meaning of each enum value for 'type' (company vs drug) and prescribes the format for 'values' (tickers/CIKs for company, names for drug) with cardinality constraints. 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 performs side-by-side comparisons of 2–5 companies or drugs in one call, distinguishing it from sequential lookups. It provides example queries like 'compare X and Y' and 'rank these companies', making the purpose immediately clear.

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

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

Explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also specifies the entity types and the number of entities (2–5), leaving no ambiguity about invocation context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral context: parallelism, evidence format, gaps for unanswered facets, citations, and typical response time (15-60s). 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 dense paragraph, but it is well-structured and front-loaded with the key value proposition. Every sentence provides necessary information without redundancy. Slightly long but justified by complexity.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (structured findings packet with evidence, confidence, source, fetched_at, citations, gaps). It covers purpose, usage, parameters, behavioral traits, requirements, and timing. Very complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'question' should be natural language and broad/multi-part is fine, and that 'depth' controls number of facets (quick=3, standard=5, thorough=8). Also mentions plan dependency for thorough.

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: 'Grounded multi-source research in ONE call.' It explains the decomposition and parallel querying mechanism, and distinguishes from sibling 'ask_pipeworx' which is for single lookups.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups.' Also mentions account requirements and plan limitations.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed'. This goes beyond what annotations provide.

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

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

The description is thorough but not overly long. It front-loads the core purpose and then provides domain examples and return information. A slight redundancy exists (the return format is mentioned twice), but overall it is well-structured and informative.

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

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

For a tool designed to discover other tools, the description covers purpose, usage, input semantics, output format, and behavior. No output schema exists, but the description explains exactly what is returned. It is complete and self-contained, providing all needed context for an AI agent to use it 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% with all parameters described. The description adds value by providing concrete examples of what 'query' should contain (e.g., 'analyze housing market trends', 'look up FDA drug approvals') and mentioning aliases, which reinforces the schema info.

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 'Find tools by describing the data or task' with a specific verb and resource. It lists many example domains and explicitly positions itself as the tool to call 'FIRST' to see the option set, distinguishing it from sibling tools that perform specific searches or analyses.

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 usage context: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It implies that if you already know which tool to use, you don't need it, but does not explicitly state exclusions or alternatives. The sibling list suggests alternative specialized 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?

The description discloses key behaviors beyond annotations: it fans out across multiple APIs (SEC, XBRL, USPTO, news, GLEIF), uses fallback mechanisms (GDELT→GNews), soft-fails for patents, and returns specific data fields with URIs. Annotations confirm idempotent, read-only, open-world behavior, and the description adds valuable context 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 thorough but slightly verbose. It is front-loaded with example queries, which is good. Every sentence adds useful information, but some redundancy exists (e.g., restating that names are not supported in both description and schema). Overall efficient for the complexity.

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

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

Given no output schema, the description fully compensates by detailing return fields, API sources, fallback behavior, and limitations (patents soft-fail, name support). It addresses all aspects a user or agent would need to understand the tool's functionality and interpret results.

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 already provided. The description adds meaning by clarifying that names are not supported, zero-padded CIK is required, and gives examples. This supplements the schema well, though the schema itself already covers the basics.

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 defines a specific verb ('profile') and resource ('US public company'), and distinguishes from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It lists multiple data sources and return fields, providing a precise 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?

The description gives clear when-to-use guidance with example queries and a preference statement. It advises using resolve_entity first if only a name is available. It lacks explicit when-not-to-use scenarios but effectively implies that for granular single-source queries, other tools are better suited.

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 readOnlyHint=false. The description adds context about clearing sensitive data, but the core destructive nature is already clear 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?

Two sentences, zero waste, front-loaded with the action. Every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description adequately covers purpose, usage, and behavioral 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 covers 100% of parameters; the description simply restates 'by key.' No additional parameter meaning is provided beyond the schema's minimal 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 'Delete a previously stored memory by key' (verb+resource). It distinguishes from siblings by explicitly mentioning 'Pair with 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 when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also cites alternatives by naming 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=true and destructiveHint=false, indicating a safe read operation. The description adds useful behavioral context: fetches the page, extracts title/description/key links, emits standard llms.txt format, and outputs a single text blob. 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 plus a use-case list, all front-loaded. Every sentence adds value: purpose, process, output format, usage scenarios. 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 simple tool (2 params, no output schema, rich annotations), the description covers the output format, process, and deployment location. It is complete enough for an agent to understand what the tool does and what it returns. Minor gap: no mention of error handling or URL validation, but not critical.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description does not add additional meaning beyond the schema, e.g., it does not clarify url format or max_links defaults further. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('generate'), resource ('llms.txt file'), and target ('any URL'). It distinguishes the tool from siblings by focusing on a specific output format and use cases (indexing by AI crawlers, drafting, auditing). Siblings like ai_visibility_check and scan_competitor_ai_presence are different in 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?

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing a competitor). It implies when to use (for generating llms.txt) but does not explicitly state when not to use or provide alternatives. Sibling tools exist but are not mentioned.

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, destructiveHint=false, etc. The description adds useful behavioral context: the tool requires a specific id format, and it returns specific fields. 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 sentences, front-loaded with the action, no redundant information. Every sentence contributes to understanding the tool's purpose and constraints.

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 parameter, no output schema) and rich annotations, the description fully covers the necessary context: what it does, what it returns, and input constraints. 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 a description for the 'id' parameter. The description goes beyond the schema by providing concrete examples (SPAC1002.01) and clarifying that standard names are not accepted, adding practical value.

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

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

The description explicitly states the action 'look up a gene' with the resource 'PomBase systematic id' and lists specific return fields (product, domains, viability, etc.). It distinguishes from sibling tools by mentioning it complements SGD.

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 states when to use (when a systematic id is available) and when not (standard gene names not accepted). It also provides context about complementing SGD, helping the agent choose between tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds value by specifying 'Keyless' (no auth needed) and listing return fields.

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 with example and keyless note, no wasted words. Highly 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?

For a simple one-param lookup without output schema, description adequately lists return fields. Minor gap: no mention of error handling or rate limits, but not critical.

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

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

Schema covers the pmid parameter fully (100% coverage). Description adds an example but no additional semantic information beyond the schema.

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

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

Description clearly specifies verb 'look up' and resource 'curated S. pombe publication' with explicit output fields. Distinguishes from siblings like get_gene and 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 input format example but lacks explicit guidance on when to use vs alternatives or any exclusion criteria. Usage is implied but not explicitly stated.

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 fields returned and default behavior (active only). Annotations already confirm read-only, idempotent, non-destructive; description adds 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, front-loaded with purpose, then usage context. No redundant or missing 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?

Covers purpose, usage, return fields, and single parameter. No output schema exists but description sufficiently explains return data.

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 parameter description is adequate. Description adds no new info beyond schema, meeting 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?

Specific verb 'List' and resource 'subscriptions' with explicit scope 'caller's active subscriptions'. Distinguishes from sibling tools like subscribe, unsubscribe.

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

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

Provides clear when-to-use guidance: review monitoring before adding more or find id to cancel. Implicitly excludes creating or modifying subscriptions.

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 valuable behavioral context beyond annotations: it is rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also states that the team reads digests daily and signal affects the roadmap. Annotations already indicate non-readonly, non-idempotent, non-destructive, so this adds detail 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?

Every sentence serves a purpose: defines action, gives usage examples, provides formatting advice, mentions rate limits and roadmap impact. It is front-loaded with the core purpose and wastes no words. Despite multiple sentences, 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?

Given there is no output schema, the description explains what happens after submission (team reads daily digests, signal affects roadmap) and mentions rate limits. Schema covers all parameters. The tool is simple, and the description provides sufficient context for an agent to use it 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 description coverage is 100%, so baseline is 3. The description goes beyond schema by advising to describe issues in terms of Pipeworx tools/packs, and explains the feedback categories (bug, feature, etc.) in context. This adds practical guidance for constructing the message parameter.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, or praise. It specifies the exact types of feedback (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by focusing on direct team communication rather than data retrieval or other actions.

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

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

The description provides explicit when-to-use guidance: broken/stale data (bug), missing tool (feature/data_gap), or surprising success (praise). It also advises against pasting end-user prompts, and mentions rate limits (5 per identifier per day) and that it's free, helping the agent decide when to invoke this tool over others.

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. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). Fully transparent.

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

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

Three sentences, each serving a purpose. Front-loaded with result. No wasted words. Efficient and clear.

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

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

For a simple tool with 1 param and no output schema, description covers all needed context: inputs, outputs, use cases, behavior, and data source. 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 window parameter with enum and description. Description adds meaning: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over a time window. Uses specific verb 'returns' and resource 'trending data'. Distinguishes from siblings like discover_tools or get_reference.

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 three explicit use cases (discovering hot data, confirming canonical tool, aligning use case). Does not explicitly state when not to use, but context is clear. Could mention alternatives like discover_tools for broader discovery.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral details: it checks fill risk via market depth, uses Jaccard similarity for semantic anchoring, filters partition placeholders, and explains the fill check. 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 relatively long but front-loaded with the required condition. Every sentence adds value (modes, checks, response structure, fill risk). Minor improvement possible by using bullet points or clearer section breaks.

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 explains the response (opportunities array, partition_check object, fill_check details). It covers complex aspects like semantic anchoring, partition filtering, and links to a sibling tool for further handling, making it complete for a complex analysis tool.

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

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

Schema coverage is 100%, and the description adds context for both parameters: 'event' accepts slugs or URLs, 'topic' is a seed question. It clarifies the modes (single-event vs cross-event), which goes beyond the schema descriptions alone.

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: finding arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between 'event' mode (single-event) and 'topic' mode (cross-event), and contrasts with sibling tools like 'polymarket_fill_risk' for custom sizing.

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 notes that one of 'event' or 'topic' is required and that calling with no args fails. It provides clear recommendations (event recommended for specific markets, topic for cross-event scanning) and guidance on when not to trade (if realizable_edge_pp ≤ 0), directing to a 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes far beyond by detailing three model families, edge calculation (edge_pp_net, kelly_fraction), response segments, diagnostics, caching policy (1h KV-level), and data sources (FRED, GDELT). 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 extremely detailed and technical, covering all aspects of the tool's logic, but it is verbose and lacks structured formatting (e.g., bullet points or sections). While every sentence adds value, the density makes it hard to parse quickly.

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 the absence of an output schema, the description comprehensively explains the response structure (by_segment with three segments, diagnostics, fed_candidates), per-opportunity fields, all filter knobs, and data sources. It is complete for a complex analytical tool.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds high-level context such as 'Tradeable-edge knobs' but does not significantly enhance understanding of individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for the 'what should I bet on today' use case, with specific model families and segments. Although it does not explicitly distinguish from siblings, the purpose is precise and actionable.

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

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

The description implies usage for discovering betting opportunities without paging hundreds of markets, but it does not explicitly state when to use this tool over siblings like polymarket_arbitrage or when not to use it. No exclusions or alternative recommendations are provided.

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

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

Description adds context beyond annotations, explaining it reads snapshots, provides time-series, and mentions limits (60-day TTL, not intraday). No contradictions; readOnlyHint and idempotentHint are confirmed.

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

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

Description is dense but each sentence adds value. Could be more structured (e.g., separate sections), but front-loads purpose and explains response fields clearly. Not overly verbose.

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

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

For a tool with no output schema, description thoroughly explains response fields (tracked, expired, snapshot_dates) and limits. Missing potential edge cases like empty results, but overall very complete.

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

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

Schema coverage is 100%, but description adds value by explaining 'days' as lookback with default and max, and 'window' as snapshot family with default. Provides context on how parameters affect output.

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 provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and trend, distinguishing from sibling tools like polymarket_edges.

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

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

Implied usage through parameter descriptions and limits (e.g., history depth, TTL), but no explicit guidance on when to use this tool versus alternatives like polymarket_edges or 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, openWorld, idempotent, non-destructive. Description adds significant behavioral details: walks the ladder, returns fill metrics, warns about thin legs and forced directional risk. No contradiction with annotations.

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

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

Description is thorough (200+ words) but well-structured: core purpose first, then REQUIRES, then clear sections for modes, then usage guidance. Each sentence adds value. Could be slightly more concise but remains efficient.

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

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

No output schema exists, so description must compensate. It thoroughly lists return fields for both modes (e.g., top_of_book, vwap_fill_price, thin_legs, forced_directional_risk) and explains their significance. Given tool complexity, completeness is excellent.

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

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

Schema coverage is 100% (baseline 3), but description substantially enriches meaning: explains single-market vs basket mode purpose, default logic for side, and interpretation of size_usd for basket as 'settlement notional — shares per leg'. Provides context beyond schema.

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

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

Description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' for Polymarket. It distinguishes between single-market and basket modes, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: partial fills convert arb to directional risk, and theoretical overround on thin books is not capturable. Also details specifics for each mode.

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 covers behavior beyond annotations: it explains compatibility_warning cases, temporal_alignment, skipped counters, and leg-by-leg prices. Annotations (readOnlyHint, idempotentHint, etc.) are fully consistent with the description.

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 well-structured: front-loaded with purpose, then details modes, response, and safety fields. Every sentence adds value, though it could be slightly more 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 (cross-venue comparison) and no output schema, the description thoroughly covers response structure, safety fields, and edge cases like compatibility_warning and temporal_alignment. It is complete for agent usage.

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

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

Schema coverage is 100% with descriptions, and the description adds context: topic is a pre-mapped shortcut list, explicit tickers override, and explains their interplay. This significantly adds meaning beyond the schema alone.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifying the verb (compute/retrieve) and resource (spread). It distinguishes itself from siblings like polymarket_arbitrage and compare_entities by focusing on cross-venue comparison.

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

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

The description details two modes (topic shortcuts and explicit tickers) and warns that 'pre-mapped ≠ tradeable' and real spreads are rarer. It implies when to use (when comparing same question across venues) and when not (if compatibility warning fires), though it does not explicitly 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: scoping to identifier and listing behavior when key omitted. 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?

Four sentences, no fluff. First sentence states core functionality, second adds use case, third adds scoping, fourth pairs with siblings. 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?

Simple tool with one optional param; description covers both usage modes (with/without key) and scoping. No missing information for an agent to use it 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% and parameter description already mentions omitting key to list all. Tool description reinforces this but does not add new semantic 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?

Clearly states verb ('Retrieve' or 'list'), resource (memory key/value), and distinguishes from siblings (remember, forget). The description is specific and 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?

Provides clear use case: 'look up context the agent stored earlier without re-deriving from scratch.' Mentions pairing with remember and forget. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, safe operations. The description adds behavioral details: the effect of mark_read on next calls, polling suitability, and the alternative HTTP endpoint. This goes beyond the annotations without contradicting them.

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 purpose, and every sentence adds value. No extraneous information. Structure is clear and efficient.

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

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

Given the tool has no output schema but good annotations and schema coverage, the description covers return fields, filtering options, side-effects of mark_read, polling behavior, and an alternative access method. This is 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 for each parameter. The description adds value by providing an example filter type ('sec_8k'), explaining that 'since' expects an ISO timestamp, and clarifying the 'mark_read' parameter's effect on subsequent calls. This complements 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 pulls fired events from the subscription feed, specifies the returned fields (source, citation_uri, raw payload), and uses a specific verb 'Pull'. The resource is well-defined as 'fired events from your subscription feed', making the tool's purpose unambiguous.

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

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

The description mentions that polls work fine and provides an alternative REST endpoint for scripts/dashboards, giving context for when to use this tool. However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or provide when-not-to-use guidance, slightly reducing clarity.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds significant behavioral context: fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic (GDELT→GNews), soft-failure for USPTO, and return structure (changes grouped by source with citation URIs). No contradictions with annotations.

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

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

The description is moderately long but front-loaded with concrete examples. Every sentence adds value, and the structure flows naturally from examples to internal behavior to parameter details and alternatives. Could be slightly more concise, but still 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 the return format (changes[] grouped, total_changes count, citation URIs), explains source behavior and fallbacks, and describes failure modes (USPTO soft-fail). This is comprehensive for a multi-source aggregation tool with moderate 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 description coverage is 100%, but the description adds value by explaining relative shorthand for `since` (e.g., '7d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It does not add extra information for `value` or `type`, but the added info for `since` is useful beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, with example queries like 'What's new with X' and explicitly distinguishes itself from the sibling tool 'entity_profile' which provides static profiles. The verb 'change feed' and resource 'company in last N days' are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance with common query patterns, typical `since` values ('30d', '1m'), and explicitly states when not to use it: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior, helping the agent choose correctly.

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

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

Adds context beyond annotations: explains scoping by identifier, persistence duration (authenticated vs anonymous, 24h limit). Aligns with idempotentHint=true and destructiveHint=false.

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

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

Three sentences, front-loaded with purpose, then usage, then 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 2-param tool with no output schema, the description covers all needed aspects: purpose, when to use, scope, persistence, and companion tools.

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

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

Schema already describes key and value with examples. The description reinforces by providing real-world usage patterns (e.g., 'resolved ticker', 'target address'), adding semantic richness.

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 ('Save') and a clear resource ('data the agent will need to reuse later'). It explicitly distinguishes from sibling tools 'recall' and 'forget', making it easy to differentiate.

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

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

States when to use ('when you discover something worth carrying forward') and what for (avoid re-lookup). Also references companions: 'Pair with recall to retrieve later, forget to delete.'

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 valuable context: it cascades through multiple endpoints, auto-disambiguates company inputs, and details the return format including citations. 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 (~100 words), well-structured with example queries, a usage directive, and clearly formatted SUPPORTED TYPES section. Every sentence adds necessary information with no redundancy or filler.

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 moderate complexity (two entity types, no output schema), the description adequately covers what each type returns and positions the tool as a replacement for manual lookups. It could potentially mention error behavior or partial match handling, but overall provides sufficient context for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter understanding by explaining accepted formats (ticker, CIK, name for company; brand/generic for drug) and mentioning auto-disambiguation. This adds significant value 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 clearly states the tool resolves names to identifiers, using verbs like 'resolve' and 'look up', and provides examples for company and drug types. It implicitly differentiates from siblings by positioning it as the first step for ID needs, but does not explicitly name 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 explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear positive guidance. It also notes it replaces multiple manual lookups. However, it does not specify when not to use or contrast with specific 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, destructiveHint. The description adds process details: probes each entity, ranks, returns ranked list. 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 plus a parenthetical example; front-loaded with the main action and purpose. Zero 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?

Explains output (ranked list with score, confidence, signal density) despite no output schema. Annotations cover safety. Sufficient for a read-only comparison 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 the description adds value by specifying that the first entry of entities is treated as the 'subject' for narrative, which is not in 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 it compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each, ranking by score, and surfacing most/least recognized. It distinguishes from the 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 describes use in competitive AI-marketing audits with an example question. It implies usage vs. single-entity check but does not explicitly state when not to use or list alternatives.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds behavioral traits beyond annotations: fan-out across external services, partial failure handling (bundlephobia timing), graceful degradation with sources_failed list, and detailed 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?

The description is detailed but each sentence adds value. It front-loads the key purpose ('Composite check...'). Some minor redundancy (e.g., listing bundle fields twice) could be trimmed, but overall well-structured for an AI agent.

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 details the return structure: summary block fields, per-advisory detail, links, alternative versions, and sources_failed for partial failures. This is comprehensive for a tool without an output schema.

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

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

Schema coverage is 100% with descriptions for both parameters (package name, optional version). The description adds meaning by specifying scoped packages accepted, version defaults to latest, and the composite behavior that uses both services. This adds value but the schema already does the heavy lifting.

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 packages covering deps.dev and bundlephobia, with specific verb 'scan dependency' and resource 'npm package'. It distinguishes from siblings by focusing on npm ecosystem and answering safety/popularity/size questions.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM only in v1 and mentions fallback for other ecosystems, which guides correct 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?

Annotations already declare safe, read-only, idempotent behavior. The description adds concrete implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that every passage has offsets for verification. This goes beyond what annotations provide.

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

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

The description is a single paragraph but well-ordered: purpose, usage, pairing, technical details. Every sentence adds value, no fluff. Could be broken into bullet points for better scanability, but it's 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?

Despite no output schema, the description explains return format (passages with offsets and scores), technical engine, truncation behavior, and pairing advice. It covers all necessary context for effective use of this semantic search tool.

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

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

Schema coverage is 100%, so the description adds limited new meaning beyond schema. It includes example queries for the 'query' parameter, which adds some value, but largely restates 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 'Semantic search INSIDE a fetched record' with a specific verb (search inside) and resource (record/text). It distinguishes from siblings by describing when to use it (record too big for prompt) and pairing with 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 suggests a complementary tool (ask_pipeworx_grounded). Does not explicitly mention when not to use, but the guidance is clear and helpful.

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 idempotentHint=true, but the description does not clarify if creating a duplicate subscription returns a new ID or updates the existing one. It adds auth requirements and delivery caps (SMS 10/day), which are useful 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 dense and informative but could benefit from bullet points or clearer sectioning for readability. It front-loads the main purpose, but the length may reduce quick scanning.

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

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

Covers purpose, auth, types, and parameter examples. Missing explicit mention of return value format beyond 'subscription id' and idempotency behavior. Adequate for a complex tool without 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 coverage is 100%, but the description adds significant value with concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topic) and detailed delivery channel constraints (HMAC signing, auto-disable after 10 failures).

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream', providing a specific verb and resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 the requirement for a Pipeworx OAuth account (anonymous/BYO cannot persist). Provides examples for each subscription type, guiding when to use each. Could be more explicit about when not to use this tool versus alternatives like 'recent_alerts'.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context about returning category-bucketed examples and the exact tool+argument shapes, which is useful beyond annotations. No contradictions.

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

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

The description is a single, well-structured paragraph with clear starting point and parenthetical examples. While it packs information efficiently, it could be slightly more concise without losing clarity.

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

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

The tool is simple with one optional parameter and no output schema. The description fully explains what it returns (category-bucketed example questions with exact tool and argument shapes) and when to use it. No additional context 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 description for the optional `topic` parameter. The description adds value by listing example topic values (finance, pharma, etc.) and clarifying that omitting the parameter yields a cross-category spread, enriching the schema's explanation.

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 the onboarding entry point for a new agent, returning category-bucketed example questions with tool and argument shapes. It uses specific verbs ('suggest', 'return') and distinguishes itself from sibling tools by emphasizing its role for initial discovery.

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

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

The description explicitly advises using this tool first when the agent does not know what Pipeworx can do, and to learn how to call meta-tools. It also explains the `topic` parameter for narrowing the focus. While it does not list explicit when-not-to-use scenarios, the context is clear.

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

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

Annotations already indicate non-read-only (false) and non-destructive (false). The description adds valuable behavioral context: ownership enforcement and that the row is deactivated (not deleted), ensuring historical events remain. This complements 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?

Three sentences, each earning its place: purpose, constraint, and effect. No wasted words, front-loaded with the core action. 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 one-parameter tool with no output schema, the description covers the main points: action, ownership constraint, and post-effect. It could optionally address error cases (e.g., non-existent id) but is otherwise complete.

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

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

Schema description coverage is 100%, with the 'id' parameter well-described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter meaning beyond 'by id', so it meets the baseline.

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

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

The description clearly states the tool cancels a subscription by id. It uses a specific verb 'Cancel' and resource 'subscription'. It distinguishes itself from sibling tools like subscribe (which creates) and list_subscriptions (which lists) by focusing on cancellation.

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 an important usage guideline: ownership is enforced, indicating this tool should only be used for the current user's subscriptions. However, it lacks explicit when-to-use or when-not-to-use comparisons with siblings, such as stating it's the counterpart to subscribe.

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, openWorldHint, idempotentHint, destructiveHint=false) already signal safety and side-effect-free behavior. The description adds meaningful context: the domain (company-financial via SEC EDGAR + XBRL), return format (verdict, citation, delta), and that it replaces multiple calls. 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 front-loaded with natural-language triggers, which is good. However, it is slightly verbose (3 sentences, ~100 words). Some phrases like 'via SEC EDGAR + XBRL' could be integrated more concisely. Still, every sentence contributes value.

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

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

Despite no output schema, the description covers return values (verdict types, citation, delta) and the tool's scope. For a single-parameter tool with rich annotations, it provides enough context for an agent to use it correctly. The only gap is not mentioning any limitations or edge cases (e.g., only US companies).

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing example claim formats ('Apple's FY2024 revenue was $400 billion') and explaining that it accepts natural language, which is richer than the schema's generic description. This helps the agent understand the parameter's format and scope.

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 ('check', 'verify', 'confirm', 'refute') and clearly identifies the resource ('natural-language claim verification against authoritative sources'). It distinguishes itself from 41 sibling tools by explicitly stating it replaces 4–6 sequential calls, which is a unique value proposition.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' Also scopes to company-financial claims, effectively telling the agent when not to use it. Could be improved by adding a clear 'do not use for' section.

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