Govdata De

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

Annotations already indicate readOnly, idempotent, etc. Description adds cost implications (free vs BYO key) and that the API key is passed through directly, which is useful behavioral context beyond annotations.

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

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

Two sentences, each delivering critical info: what it does, default model, key behavior, return structure, and use cases. 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?

For a tool with 4 parameters, no output schema, and no nested objects, the description covers purpose, parameters, behavior, and return format comprehensively. 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%, baseline 3. Description adds meaning beyond schema: default model, when _apiKey is needed, purpose of context 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?

Clearly states verb (probe), resource (LLMs), and output (score 0-100). Distinguishes from sibling tools like deep_research by focusing on visibility scoring, with specific use cases mentioned.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Could be improved by briefly noting when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it routes to 4,491 tools, fills arguments automatically, and returns structured answers with citation URIs. It also notes it's a single fast call working on all tiers. 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 longer but well-structured: it opens with the key advantage, lists use cases, provides examples, and gives guidance on alternatives. Every sentence adds value, though it could be slightly more concise. The structure is logical and front-loaded with the most important information.

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

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

Given no output schema, the description mentions the return format ('structured answer with stable pipeworx:// citation URIs'). It covers when to use this tool vs. alternatives, input format (natural language question), and scope. It is sufficiently 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 clear descriptions for all parameters (including aliases). The description does not add extra parameter-level detail beyond the schema, but the included examples help illustrate usage. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions using authoritative structured data from thousands of sources. It explicitly contrasts with web search and distinguishes from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', lists numerous example use cases, and specifies when to use alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for broad questions). Examples like 'current US unemployment rate' and 'Apple's latest 10-K' illustrate appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: returns structured success/refusal responses, lists specific refusal reasons (not_in_source, no_tool_match, etc.), and mentions the extra LLM call cost. No contradictions.

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

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

Description is well-structured: starts with purpose, explains routing and extraction process, details output format and refusal reasons, gives usage guidance, and notes cost trade-off. Every sentence adds value with no redundancy. Length is appropriate for the complexity.

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

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

Despite no output schema, the description fully explains the return format for both success and refusal cases, including specific refusal reasons. It covers routing logic, cost implications, and appropriate usage contexts. Provides a complete picture for the agent to understand behavior.

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

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

Schema coverage is 100% with all parameters described (question and its aliases). The description does not add any additional semantic detail about parameters beyond what is in the schema, so 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?

Clearly states 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of picking the right tool, fetching data, and extracting answer using only tool result. Distinguishes from sibling 'ask_pipeworx' by specifying grounded extraction and refusal mechanism. Provides explicit use cases for when quoting or citing is needed.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples like financial verdicts, legal claims. Also advises 'prefer ask_pipeworx for casual lookups' due to extra cost, clearly guiding when to use this tool vs the alternative.

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

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

The description adds extensive behavioral context beyond annotations, detailing fan-out patterns, response shapes, resolver contract, parent event extractor, news fields, safety short-circuits, wide-spread markets, and resolution-rule risk. Annotations indicate readOnly, idempotent, non-destructive, which the description aligns with and expands upon. 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 quite long and detailed, which is justified by the tool's complexity, but it could be more structured. It front-loads the main purpose but then dives into specifics without clear sectioning.

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

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

For a tool with 3 parameters and no output schema, the description is remarkably complete. It covers response shapes, edge cases, safety mechanisms, resolution risk, and fallback behavior, compensating fully for the lack of 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%, so baseline is 3. The description adds significant value beyond the schema by explaining market input types, depth parameter behavior, and include_raw purpose with examples and trade-offs.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It uses specific verbs like 'Research' and 'pull', specifies the resource 'Polymarket bet', and distinguishes from siblings like ask_pipeworx or polymarket_edges by focusing on this specific use case.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It includes examples of classifiers and fan-outs. However, it lacks explicit when-not-to-use or alternatives, though 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?

The description adds significant behavioral context beyond annotations: it performs a single parallel call (efficiency), handles off-calendar fiscal years correctly, sorts results by primary metric so the 'largest' appears first, and returns paired data with citation URIs. Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint, so 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 relatively long but efficient: it front-loads trigger phrases, packs essential details (data sources, sorting, citation URIs), and avoids redundancy. A minor trim could improve conciseness, but every sentence earns its place.

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

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

Given the complexity (two entity types, multiple data sources, citation output) and no output schema, the description fully covers what the tool returns ('paired data + pipeworx:// citation URIs'), how it behaves (parallel call, sorted results), and the entity-specific data fields. It is complete enough for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: for type, it explains that 'company' pulls LATEST 10-K financial data from SEC EDGAR/XBRL and 'drug' pulls FAERS/FDA data. For values, it gives examples (tickers/CIKs for company, names for drug) and the allowed count range (2–5). This goes well beyond the schema's concise 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 opens with user intents like 'Compare X and Y' and states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It clearly identifies the resource (entities: companies or drugs) and the action (compare). It also distinguishes from sequential lookups, making the purpose unmistakable.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool. It also lists example queries ('compare X and Y', 'which is bigger') that signal appropriate usage, effectively steering the AI away from alternatives like entity_profile.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that it never invents answers (gaps[]) and explains internal decomposition and parallel tool routing. 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 long but warranted given complexity. Front-loads critical prerequisite (account). Each sentence provides unique value. Could be slightly more concise but remains well-organized.

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?

Comprehensive for a research tool without output schema. Describes return format (evidence, confidence, source, timestamps, citations, gaps[]) and failure modes (returns empty gaps for non-structured topics). Covers best uses and limitations.

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

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

Schema coverage is 100% with descriptions. Description adds context for depth parameter (quick=3, standard=5, thorough=8) and reiterates that broad/multi-part questions are fine. Adds marginal value beyond schema.

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

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

The description clearly states it performs 'grounded multi-source research across structured data sources' and returns a findings packet. It distinguishes from sibling tools like ask_pipeworx, specifying that deep_research is for broad/multi-part questions and not for open-web or breaking news.

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 account requirement and alternative if not signed in (ask_pipeworx). Provides concrete guidance on when to use (broad/multi-part structured questions) and when not (breaking/current news, single lookups). Also mentions expected latency.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds valuable context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond 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 two dense sentences that front-load purpose and usage. It includes a long list of examples, which is necessary for clarity but slightly reduces conciseness. Overall, it is well-structured and efficient, earning a 4.

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

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

Given the complexity (6 parameters, no output schema), the description covers the important aspects: what the tool returns (top-N relevant tools with schemas and examples), and how to use it (first when exploring). The limit parameter is explained. It is nearly complete for its role as a tool discovery 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 schema already documents all parameters. The description mentions the alias behavior ('Accepts task, q, description, search as aliases'), which adds minimal extra meaning beyond the schema. Baseline of 3 is appropriate as the description does not significantly add 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 verb+resource: 'Find tools' and specifies the domains (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by instructing 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This fully meets the criteria for a 5.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...'. It provides ample context for when to use, but does not explicitly mention when not to use or list alternatives. However, the sibling tool list suggests other specific tools, so the guidance is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds rich behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), notes that patents may soft-fail due to API sunset, describes fallback for news, and specifies return fields with URIs. No contradiction with annotations.

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

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

The description is well-structured with query examples first, then priority guidance, followed by sources and return details, then input requirements. Every sentence adds value, though it is relatively long. Could be slightly more concise without losing clarity.

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

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

Given no output schema, the description adequately explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail). It covers the key aspects of what the tool returns, though the exact format (JSON or text) is not specified.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces the same info (ticker or CIK, names not supported) and adds the nuance that CIK should be zero-padded. While this adds slight value beyond the schema, the schema already covers the essentials well.

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 concrete query examples and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb (profile) and resource (company), and distinguishes from siblings by explicitly preferring this over chaining individual lookups. It also notes to use resolve_entity for names, differentiating from that sibling.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides specific instructions on input format (ticker or CIK, not names) and directs to use resolve_entity first if only a name is available. This gives clear when and when-not guidance.

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

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

Annotations already indicate destructive and idempotent. Description adds context about clearing sensitive data, consistent with deletion.

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

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

Two efficient sentences, front-loaded with core purpose, no redundant 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?

Simple tool with full coverage: purpose, usage, alternatives, and no missing aspects.

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

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

Schema covers parameter 'key' fully with description; description does not add beyond purpose, but schema suffices.

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

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

Clear verb 'Delete' with resource 'memory' and specificity 'by key'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Mentions pairing with remember and recall as alternatives.

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

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

Annotations already declare readOnlyHint (non-destructive) and idempotentHint. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format. This provides process context beyond the annotations, though it omits potential issues like JS-required sites or rate limits.

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: 2-3 sentences covering purpose, process, output, and usage. It is front-loaded with the core function and avoids redundancy. Every sentence adds value.

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

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

Given the tool's low complexity (2 params, no output schema, read-only), the description sufficiently covers inputs, process, and expected output. It does not explain error handling or limitations (e.g., dynamic content), but for a straightforward read-only tool this is acceptable.

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

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

Schema coverage is 100% (both url and max_links are described in the schema). The description does not add extra semantic detail for the parameters beyond restating their role. Baseline 3 is appropriate as the schema 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 uses a specific verb 'generate' and identifies the resource 'llms.txt file for any URL'. It clearly distinguishes the tool from siblings by explaining its unique output format and target use case.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor AI visibility. It does not include when-not-to-use, but the tool's purpose is narrowly defined so no exclusion is critical.

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, so the tool is safe and idempotent. The description adds value by listing the specific fields returned and clarifying the scope (caller's active subscriptions), which aligns with and complements the annotations.

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

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

The description is extremely concise, with two sentences covering purpose, return fields, and usage guidance. There is no redundant or extraneous information.

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

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

Given the low complexity (one optional boolean parameter, no output schema), the description provides sufficient details: it lists the return fields, explains the default behavior (active subscriptions), and ties usage to related sibling tools (subscribe, unsubscribe). It is complete for the tool's purpose.

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% (the one optional parameter 'include_inactive' is fully described in the schema). The description does not add any additional meaning beyond the schema, so 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 'List the caller's active subscriptions' and specifies the returned fields (id, type, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe by implying it's for review before adding or cancelling.

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 it to review monitoring before adding more subscriptions or to find an id to cancel. This provides clear usage context, though it does not explicitly mention alternatives.

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

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

Annotations have all hints false, but description adds critical behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, and feedback affects roadmap. This fully informs the agent of constraints and impact beyond annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence serves a purpose: type of feedback, usage guidance, behavioral constraints, and team impact. Slightly wordy but all content earns its place; minimal fluff.

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

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

For a simple feedback tool with no output schema, the description covers all necessary aspects: what it does, when to use, how to format input, behavioral limits, and impact. No gaps remain given 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 description coverage is 100%, so baseline is 3. The description reinforces the purpose of parameters (e.g., 'describe the issue in terms of Pipeworx tools/packs') but does not add substantial new semantic detail beyond what the schema's parameter descriptions already provide. No deduction needed.

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: sending feedback to the Pipeworx team. It explicitly lists feedback types (bug, feature, data_gap, praise) and distinguishes from sibling tools which are primarily data retrieval or analysis tools, making its unique function obvious.

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 scenarios: bug, feature, data_gap, praise. Also includes what not to do (don't paste end-user prompts) and how to describe issues in terms of Pipeworx tools/packs. This leaves no ambiguity about appropriate usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds data source ('CF analytics-engine'), privacy ('no PII'), and caching ('5min-1h'). No contradiction. Adds value 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?

Four sentences, front-loaded with return value, then use cases, then technical details. No unnecessary words. 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?

No output schema exists, but description specifies returned elements (tools, packs, volume) and caching behavior. Sufficient for a simple read-only trending tool; could add more detail on output format.

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

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

Schema coverage is 100% with well-described enum parameter. Description reinforces window semantics but does not add new details beyond schema. 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?

Description clearly states 'Returns the top tools, top packs, and total call volume over a recent window.' Uses specific verb 'Returns' and distinct resource. Differentiates from siblings like discover_tools by focusing on trending data.

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

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

Lists three concrete use cases (discovering hot data sources, confirming canonical choice, aligning use case). Compares window options: short for hot trends, long for steady-state. No explicit when-not-to, but sufficient guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint. The description adds substantial behavioral context: explains the detection logic (monotonicity, partition-sum), the fill check against live CLOB depth, edge cases like placeholder filters and similarity thresholds, and what happens with certain inputs. No contradictions.

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

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

The description is thorough but structured: it front-loads the requirement, then covers modes, semantic anchor, partition filter, response, and fill check. While slightly long, every sentence contributes essential detail for correct usage.

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 (two modes, internal checks, fill validation), the description covers all critical aspects. Despite no output schema, the response structure is sufficiently described. The context is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema. It explains the semantic difference between the two parameters, provides example values, describes the processing pipeline for each mode, and details the response structure. This compensates fully for the lack of output schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and provides specific examples, making the purpose unambiguous and distinct from siblings.

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

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

Explicitly states the requirement: 'REQUIRES one of event OR topic — call with no args fails.' Provides clear recommendations for when to use each mode, and directs users to an alternative tool (polymarket_fill_risk) 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 as true, and destructiveHint as false. The description adds extensive behavioral context: caching at KV level for 1h, detailed explanation of model families, edge calculation (edge_pp_net, kelly fractions), 24h-move warning, diagnostics for empty segments, and tradeable-edge knobs. 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 thorough and well-structured with sections for model families, knobs, response structure, and caching. However, it is lengthy and dense, which may overwhelm some agents. Every sentence is informative, but it could be pruned slightly without losing meaning.

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

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

Given 9 parameters, no output schema, and comprehensive annotations, the description is complete. It explains the response structure (by_segment, fed_candidates, diagnostics), why segments might be empty, caching behavior, and tradeable-edge filters. With no output schema, it fully covers return values and edge cases.

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. The description adds significant meaning beyond schema for all 9 parameters: e.g., for 'limit' it specifies default and max; for 'min_kelly' it explains it's half-Kelly and gives example; for 'category_filter' it provides comma-separated values and examples; for 'min_partition_leg_kelly' it explains application to per-leg Kelly. Each parameter's description adds practical context.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It provides a specific verb ('scan', 'return') and resource ('Polymarket markets'), and distinguishes from siblings by detailing model families like MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT, which are unique to this tool.

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

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

The description explicitly states it is built for 'what should I bet on today' and explains when to use it (discover opportunities). It mentions Fed bets are excluded from ranking, providing some exclusion criteria. However, it does not directly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, missing explicit guidance on alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds substantial detail: reading from snapshots, TTL bounds, gaps meaning no scans, decay from daily closes, and response structure. 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 detailed but each sentence adds value. It front-loads the core purpose and uses structured terms (tracked[], expired[], snapshot_dates[]). Slightly verbose but justified by the complexity of the tool.

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

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

Without an output schema, the description fully explains return values, limitations (TTL, decay computation), and data meaning. Given the tool's complexity (2 params, no nested objects), the description is thorough and leaves no critical gaps.

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

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

Schema covers both parameters with descriptions (days, window). Description repeats schema info (defaults, clamp) without adding new meaning. Since schema coverage is 100%, 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 provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering a specific question about edge age and trend. It distinguishes itself from siblings like polymarket_edges (which creates snapshots) by focusing on historical analysis.

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

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

The description provides context on when to use the tool (e.g., comparing fresh vs. old edges) and explains the history depth and decay computation. It does not explicitly state when not to use it, but the sibling list implies alternatives. Overall, usage guidance is clear but lacks explicit exclusions.

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. Description adds behavioral traits: walks the ladder, returns verdict (clean|degraded|cannot_fill), and warns about forced directional risk and thin legs. 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 longer but well-structured: first sentence states purpose, then mode-specific details, then usage guidelines. Front-loads key information. Could be slightly more concise, but it earns its length given 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?

Output schema is missing, but description lists many return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains the significance of each mode. It covers the essential information for an agent to understand tool behavior, though structured output schema would improve completeness.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). Description adds significant meaning beyond schema: explains how side behaves differently in single vs basket modes, what event vs market switches modes, and constraints on size_usd (clamp 10–1,000,000). Also explains default behaviors.

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 performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, lists return fields, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying its use before acting on those signals.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial basket fills convert to unhedged directional position). Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate read-only, open-world, idempotent. The description adds substantial behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanations of cross-type/subtype mismatches. No contradictions.

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

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

The description is thorough but efficiently structured: front-loads purpose and modes, then explains response and safety fields. 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?

With no output schema, the description explains the response format (leg-by-leg prices, matched spreads, safety fields) and covers temporal alignment and skipped counters. It is complete for a tool with 3 parameters.

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. The description enriches by listing the exact topic shortcuts, explaining that explicit tickers override topic-mapped sides, and providing an example. Adds 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 explicitly states the tool computes cross-venue spread between Kalshi and Polymarket, distinguishes between two modes (topic shortcuts vs explicit tickers), and explains when spreads are meaningful. It clearly differentiates from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use each mode (topic vs explicit) and warns that most pre-mapped topics return compatibility warnings, advising that pre-mapped ≠ tradeable. It implicitly guides against using when compatibility_warning fires, but lacks an explicit 'do not use when' statement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: scoping to identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. This enhances transparency beyond the annotations.

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

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

Three sentences at ~60 words, front-loaded with the core purpose, then usage context, then scoping. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool is simple (1 optional param, no output schema), the description covers purpose, usage, scoping, and pairing with siblings. It doesn't detail return behavior on missing key or list format, but these are minor gaps for an otherwise clear description.

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% (single parameter 'key' with description explaining its behavior). The description reinforces the behavior (omit to list all keys) and adds use-case examples, but does not significantly extend the parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's verb (retrieve/list) and resource (saved values), and distinguishes from sibling tools 'remember' and 'forget' by pairing them. It gives specific examples of usage (user's target ticker, address, research notes).

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

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

The description provides clear usage context: to look up previously stored context without re-deriving it, and notes the scoping per identifier. It implicitly guides when to use this tool (retrieve/list) vs siblings (remember/forget), but does not explicitly state when not to use it.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also specifies the return structure (source, citation_uri, raw payload). No contradictions with annotations.

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

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

The description is concise, with 4 sentences. It front-loads the main action, then adds filtering details and behavioral notes. Every sentence earns its place, with no redundancy or fluff.

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

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

Given 5 parameters and no output schema, the description covers the key aspects: return value structure, filtering, mark_read behavior, and alternative access via REST. It does not explain pagination (limit only, no cursor), but the tool is simple enough that this is adequate. Complete for its 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%, so baseline 3. The description adds context beyond schema: it provides an example for 'type' ('e.g. "sec_8k"') and explains 'since' as an 'ISO timestamp'. It also explains 'mark_read' behavior. It does not mention 'limit' or 'unread_only' but their schema descriptions are clear. Added value justifies a 4.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (recent alerts from the feed) and the verb (pull). It distinguishes from siblings like list_subscriptions by being about event retrieval, not subscription management.

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 guidance on when to use this tool versus alternatives: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' It also explains filtering options (type, since) and mark_read parameter, giving clear context for usage. While it does not explicitly exclude other tools, it implies this is for direct polling and the REST endpoint for scripts.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral context: parallel fan-out to multiple sources, fallback from GDELT to GNews on rate limits/5xx, USPTO soft-fail due to API sunset, and structured return with citations.

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?

Front-loaded with example queries, then structured explanation of sources, fallback, and return format. Every sentence is informative, no redundancy. Appropriate length for 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, description specifies return structure (changes[], total_changes, citation URIs). Covers limitations (USPTO soft-fail) and provides a reference to sibling tool entity_profile. Complete for a multi-source query 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 already covers all 3 parameters with descriptions (100% coverage). Description adds value by explaining `since` accepts ISO dates or relative shorthand (e.g., '7d', '30d') and suggests preferred values, plus clarifies `value` can be ticker or CIK.

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 the tool as a change feed for a company within a time window, with examples of queries it handles. It specifies the sources (SEC EDGAR, GDELT/GNews, USPTO) and contrasts with entity_profile for static data, effectively distinguishing from sibling tools.

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

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

Provides explicit when-to-use patterns (e.g., 'What's new with X') and when-not-to (use entity_profile for static profile). Gives guidance on `since` parameter format and suggests '30d' for typical monitoring, plus fallback behavior for GDELT to GNews.

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 idempotent, non-read, non-destructive. Description adds persistence details (24-hour vs persistent memory based on authentication), which is useful beyond annotations. Does not explicitly state overwrite behavior on same key, but idempotentHint implies it.

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 tightly written paragraphs: first sentence states purpose, second gives usage, third covers storage semantics. No wasted words, all sentences add value.

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

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

Given no output schema, description explains storage behavior and scoping but does not mention return value (e.g., success confirmation). Otherwise complete for a write operation with decent annotations.

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

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

Schema already has good descriptions for key (with examples) and value (any text). Description adds little extra meaning beyond usage context; baseline of 3 is appropriate given high schema_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?

Description clearly states verb 'Save' and resource 'data the agent will need to reuse later', specifying it as a key-value pair. It distinguishes from sibling tools 'recall' and 'forget' which are explicitly mentioned.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides context for when to avoid (if not needed later). References companion tools 'recall' and 'forget' for retrieval and deletion, giving clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds value by disclosing internal cascading through multiple lookup endpoints and stating it replaces 2-3 manual lookups. This provides behavioral context beyond annotations.

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

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

The description is approximately four sentences, front-loaded with user-facing examples. Every sentence provides essential information without redundancy. No wasted words, making it highly readable and efficient.

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

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

Given the tool's complexity (two entity types with different outputs) and the absence of an output schema, the description is reasonably complete. It lists return fields for each type and explains the multi-step internal logic. Some details like exact output structure or error handling are omitted, but the description covers core behavior adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: for 'company' it returns ticker, 10-digit CIK, company_name, and citation URI; for 'drug' it returns RxCUI, ingredient, brand, and citation URI. It also explains acceptable input formats for 'value' (ticker, CIK, name for company; brand/generic for drug). This goes well beyond the schema's brief descriptions.

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

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

The description specifies the tool's purpose as resolving user-spoken names to canonical/official identifiers. It uses a specific verb ('resolve') and resource ('entity identifiers'), and provides clear examples ('ticker', 'CIK', 'RxCUI'). It distinguishes itself from siblings by being the go-to for name-to-ID conversion.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use the tool. It does not explicitly exclude scenarios or mention sibling alternatives, but the guidance is adequate for effective selection.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns 'ranked list with score, confidence, signal density per entity.' It also mentions optional models and API key usage. 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?

Three succinct sentences. The first sentence states the core action, the second explains the process, and the third provides a use case example. No fluff.

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

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

With no output schema, the description does well by listing returned fields (score, confidence, signal density) and format (ranked list). However, it does not specify the exact JSON structure or data types, which would provide more completeness for an agent.

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

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

All 4 parameters have 100% schema description coverage, but the description adds significant value: it notes that the first entity is treated as 'subject' for narrative, explains model omission behavior, and clarifies that _apiKey is only needed for anthropic. These details go 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 'Compare AI visibility across multiple entities side-by-side' and explains the process of probing with ai_visibility_check, ranking, and surfacing most/least recognized. This is specific and distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use this tool (multi-entity comparison) but does not explicitly state when not to use or mention alternatives, though the sibling list suggests ai_visibility_check for single entities.

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, and non-destructive. The description adds critical behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This exceeds basic annotation info.

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

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

The description is efficient but slightly dense. It front-loads the purpose and then packs details in a single paragraph. While not overly long, it could be structured with bullet points for readability. Every sentence serves a purpose.

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

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

Despite lacking an output schema, the description fully enumerates the return fields: 'summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions.' It also covers failure modes and ecosystem scope, making it complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting default behavior for version and the timeout nuance for bundlephobia. It could have elaborated on scoped package syntax but is sufficient.

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: a composite check for npm packages aggregating data from deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by focusing solely on npm packages, unlike other research or validation tools.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also provides alternatives: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This directly tells the agent when to use this tool and when not.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds significant context: embedding model (BGE-base-en), similarity method (cosine over 500-char windows), character cap (200K chars) with truncation behavior, and return format (passages with offsets and scores). No contradiction with annotations.

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

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

The description is a single paragraph that efficiently front-loads the purpose, then provides usage guidance and technical details. Every sentence adds value without redundancy. It is succinct yet comprehensive.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers the return format (passages with offsets and similarity scores), truncation behavior, and pairing with other tools. The annotations provide safety profile. No gaps are evident.

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 each parameter has a description. The tool description adds value by clarifying the 'text' parameter's purpose (document to search inside) and providing natural-language query examples for 'query'. It also mentions the character limit for 'text', which is not in the schema description. This justifies a score above 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 verb 'semantic search' and the resource 'inside a fetched record', and differentiates from siblings by explicitly contrasting with full-document Q&A tools like ask_pipeworx and ask_pipeworx_grounded. It provides concrete examples of usage.

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 specifies when to use this tool (when records are too large for prompts) and suggests an alternative pattern (pairing with ask_pipeworx_grounded). This provides clear guidance on selection among siblings.

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 idempotent and non-destructive behavior. The description adds valuable behavioral details: requires Pipeworx OAuth account, phone verification needed for SMS, 10/day cap, webhook auto-disable after failures, and one-time delivery of signing secret. This goes beyond what annotations convey.

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

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

The description is information-dense but structured with clear sections for types, params, and delivery. It front-loads the primary purpose. While some redundancy exists (e.g., repeating phone verification), it remains efficient overall.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers supported types, parameter constraints, delivery options, and limitations. It explains the return value (subscription id) and mentions account requirements. A minor gap is the lack of information about the frequency of event checking or latency.

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 enriches parameter understanding with concrete examples for each type and detailed explanations for delivery channels (e.g., verification requirements, webhook HMAC signing). This adds significant meaning beyond the schema.

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

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

The description clearly states the tool creates a subscription to a live-data event stream, listing supported types and delivery channels. However, it does not explicitly differentiate itself from sibling tools like list_subscriptions or unsubscribe, which slightly reduces clarity.

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

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

The description explains when to use this tool (to subscribe to alerts) but provides no guidance on when not to use it or alternatives. It lacks explicit context about using other tools for viewing or canceling 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?

Annotations already provide readOnly, openWorld, idempotent, non-destructive. Description adds that it returns live catalog data, tool shapes, and has no side effects. 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?

Compact but highly informative, uses bullet-like lists and front-loaded questions. Every sentence earns its place.

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

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

For a simple discovery tool with no output schema, description fully covers behavior, parameter usage, and use case. 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 has 1 optional param with description; description adds context: call with no args for full spread or pass topic to focus, plus lists example values. Schema coverage 100%, description adds meaningful usage context.

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

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

Clearly states it's the onboarding entry point that returns category-bucketed example questions with tool/argument shapes. Distinguishes from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes when to pass topic. No explicit when-not, but clear context 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?

The description adds value beyond annotations by detailing ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. There is no contradiction with annotations; the idempotentHint and destructiveHint are consistent.

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

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

Two sentences, each serving a clear purpose: first states the core action, second adds constraints and behavioral implications. No extraneous text, perfectly front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, constraint, behavioral effect (deactivation), and connection to sibling tool 'recent_alerts'. It is fully complete for the tool's complexity.

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

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

The single parameter 'id' is fully described in the schema (100% coverage). The description's mention 'by id' does not add new semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id' and distinguishes from sibling tools like 'subscribe' (opposite) and 'recent_alerts' (historical view). It specifies the resource (subscription) and the behavioral nuance of deactivation versus deletion.

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

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

The description explicitly states ownership enforcement (only cancel own subscriptions) and explains that deactivation preserves historical events, guiding the agent on appropriate use. It lacks an explicit 'when not to use' but provides sufficient context for typical usage scenarios.

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

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

Description adds behavioral details beyond annotations: returns a verdict with specific categories (confirmed, approximately_correct, etc.), includes a structured form, actual value with citation, and percent delta. It also explains the internal process (NL parsing, entity resolution, data lookup). No contradiction with annotations; annotations already indicate safe, idempotent operation.

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 moderately long but efficient, front-loading trigger phrases and then explaining functionality and return format. Every sentence adds value. Could be slightly tighter but overall well-structured and not 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?

Given the tool has one parameter, no output schema, but a well-described return, the description covers purpose, usage, return format, and scope (v1 limitations). It provides enough context for an agent to understand when and how to use it, and what to expect from the response.

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

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

Schema coverage is 100% for the single parameter 'claim' with a basic description. The tool description adds meaning by explaining that the claim is natural-language, providing examples, specifying the supported domain (company-financial), and describing the processing pipeline. This goes 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?

Description clearly states the tool's function as natural-language claim verification against authoritative sources, with trigger phrases. It implies differentiation from siblings by specifying it replaces multiple sequential calls, but does not explicitly contrast with other tools like ask_pipeworx_grounded or deep_research, so it misses a clear sibling distinction.

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

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

Explicitly states when to use: whenever the agent needs to check factual correctness of something a user said. It also specifies the supported domain (company-financial claims for public US companies). However, it does not clearly state when not to use or provide alternatives for unsupported claim types, leaving some ambiguity.

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