Gsa Perdiem

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds cost implication (BYO key for Anthropic) and return format details, which 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 main purpose, no unnecessary words. Each sentence contributes useful 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 4 parameters with full schema description, no output schema but explains return format, and annotations cover safety, the description fully equips an agent to use the tool correctly.

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

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

Schema covers all 4 parameters (100% coverage). Description adds context like default model and when _apiKey is needed, providing meaning 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?

Description clearly states the tool probes LLMs for business/brand visibility and scores it 0-100. It specifies verb 'probe' and resource 'LLMs' but does not explicitly differentiate from sibling 'scan_competitor_ai_presence', which may be similar.

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 usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. No explicit when-not-to-use or alternatives, but the contexts are instructive.

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. Description adds valuable context: how the tool routes queries to thousands of sources, returns structured answers with stable citation URIs, and mentions speed and tier compatibility. Does not describe error handling or output limits, but overall strong.

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 strong front-loading ('PREFER OVER WEB SEARCH') and clear sections. It is verbose but every sentence adds value; could be slightly trimmed without loss, but overall effective.

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

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

Given the tool's broad scope and simplicity (single question input), the description covers purpose, scope, usage guidance, and return value (structured answer with citation URIs). No output schema, but the description adequately hints at output format. Minor missing details on error handling or rate limits, but sufficient for an AI agent to use 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 defines 6 aliases for the same 'question' parameter with full description. The description adds minimal extra meaning beyond the schema's 'natural language' description, though the examples provide useful context. Schema coverage is 100%, 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 it answers factual questions using a vast array of structured data sources, with a specific verb ('routes') and resource ('4,770 tools across 1241 verified sources'). It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and when to step up to alternatives. Includes numerous examples illustrating appropriate use cases, and contrasts with sibling tools for depth or groundedness.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it costs one extra LLM call, specifies refusal reasons (not_in_source, no_tool_match, etc.), and clarifies that the answer is extracted only from the tool result. No contradictions with annotations.

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

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

The description is well-structured, front-loading the purpose and distinguishing features. It is dense but not overly verbose; each sentence contributes meaning. Could be slightly more concise, but overall effective.

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

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

Despite no output schema, the description thoroughly explains the return format (answer, evidence, confidence, source, etc.) and lists all possible refusal reasons. It covers success and failure modes comprehensively, making the tool's behavior predictable for the 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?

Schema coverage is 100%, with all parameters described. The description does not add new meaning beyond the schema; it only mentions aliases which are already in the schema. Baseline score of 3 is appropriate as the schema handles parameter documentation adequately.

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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling `ask_pipeworx` by emphasizing that it strictly uses tool results and provides refusal reasons. It specifies the verb (extracts answer) and resource (tool result), and differentiates from 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 states when to use this tool (high-stakes reads, when answers will be quoted/cited/acted on) and when not to (prefer ask_pipeworx for casual lookups). It lists example use cases like financial verdicts, legal claims, and medical lookups, providing clear context for selection.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: resolution logic, parent event extraction, news fallback, low-confidence/closed market handling, wide spread warnings, cancellation rule analysis, and response shape specifications. It far exceeds what annotations provide.

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

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

The description is very long and includes many details in a single paragraph. While it front-loads the core purpose, the sheer volume of information may be overwhelming. It could benefit from structuring with sections or bullet points, but it is not excessively verbose given the tool's 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 the tool's complexity (classification, fan-out, multiple data sources, response shapes, safety mechanisms, cancellation rules), the description covers virtually all aspects. No output schema exists, but the description meticulously explains response shapes (market, analysis, evidence, resolver contract, parent_event, news fields). It addresses edge cases like low confidence matches, closed markets, wide spreads, and cancellation rules.

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 3 parameters documented). The description adds value by explaining parameter usage: market input flexibility (slug/URL/question), depth options (quick/thorough with default), and include_raw summarization vs full payloads. This enhances understanding beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies multiple input formats (slug, URL, question) and output (evidence packet + market-vs-model comparison). It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on 'should I bet on X' scenarios.

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 cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-out and classifiers. While it does not explicitly list when not to use, the context is sufficient for an AI agent to decide.

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, idempotentHint=true, and destructiveHint=false, already providing a safety profile. The description adds rich behavioral detail: it pulls specific financial data from SEC EDGAR for companies, handles off-calendar fiscal years correctly, pulls FAERS data for drugs, sorts results by primary metric, and returns citation URIs. It also notes performance benefits (replaces 8-15 sequential lookups).

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 slightly long but front-loaded with example queries, followed by behavior details. Every sentence adds value, but the structure could be tighter (e.g., separate sections for company vs drug). It earns its length by eliminating the need for additional context.

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

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

Given the tool's complexity (two entity types, distinct data sources, sorting, and output format) and the lack of an output schema, the description is remarkably complete. It explains data sources (SEC EDGAR, FAERS), handles edge cases (off-calendar fiscal years), describes result ordering, and mentions return format (paired data + URIs).

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond the schema: it explains what data each type retrieves (revenue, net income for companies; adverse events for drugs), specifies the acceptable range for values (2-5), and provides concrete examples like 'AAPL' and 'ozempic'. This enriches the bare 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 that the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call. It uses specific verbs like 'Compare' and 'side-by-side comparison', and distinguishes from sibling tools like entity_profile by emphasizing parallel execution over sequential 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?

The description provides explicit usage scenarios ('X vs Y', 'which is bigger', 'rank these companies') and strongly recommends preferring this tool over sequential single-pack lookups. It does not explicitly list when NOT to use it, but the context implies alternatives are for single-entity 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds crucial context: account requirement, depth options with meaning, 15-60s expected time, that it never invents, returns gaps for unanswered facets, and provides verbatim evidence with stable citations. 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 dense but well-structured: critical account info first, then core functionality, then usage guidance, then performance expectation. Every sentence adds value, though it could be slightly trimmed without losing meaning. Front-loaded appropriately.

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 2 parameters, full schema coverage, and no output schema, the description adequately describes the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps). It also covers account requirements, depth options, and expected execution time. No gaps remain for an agent to use the tool correctly.

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

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

Schema already covers 100% of parameters with descriptions. The description enhances understanding by clarifying the depth enum values (quick=3, standard=5, thorough=8) and noting the paid plan requirement for 'thorough'. Also reaffirms that questions should be natural language and can be broad/multi-part.

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 grounded multi-source research across 1,242 structured data sources, decomposes questions into facets, and returns findings with evidence and citations. It explicitly distinguishes itself from ask_pipeworx (single lookup) and for breaking news, making the 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?

Provides explicit when-to-use (broad/multi-part structured data questions) and when-not-to-use (single lookups, breaking news, current events). Also specifies that an account is required and non-signed-in users should use ask_pipeworx instead. Offers clear alternatives.

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

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

Annotations already declare read-only and idempotent. Description adds that it returns top-N relevant tools with full schemas and examples, ready to call. 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?

Description is front-loaded with main purpose and use cases. Lists many examples which may be slightly verbose but adds helpful context. 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 simple tool with well-described parameters and no output schema, description explains return structure (schemas, examples) and default settings, making it fully actionable 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?

Schema coverage is 100% with parameter descriptions. Description adds aliases for query parameter and default/max limit values, providing extra clarity 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 discover_tools finds tools by describing data/task, lists many use cases, and explicitly says 'Call this FIRST' to see options, distinguishing it 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?

Explicitly states when to use: browsing, searching, discovering tools. Also says call first when many tools are available. Lacks explicit 'when not to use' but context makes it 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 safe, idempotent read operation (readOnlyHint, idempotentHint, destructiveHint false). Description adds valuable detail: fans out across multiple sources, returns specific fields, and discloses the USPTO API sunset (soft-fail). 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 fairly long but front-loaded with examples and key purpose. Every sentence adds context (sources, return fields, limitations). Could be slightly more structured, but overall efficient.

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

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

Despite no output schema, description thoroughly details return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and even includes URI format for filings. Covers limitations (name support, USPTO sunset). Complete for a cross-source profile 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% (2 params fully described). Description adds meaning beyond schema: explains why type is only 'company', details value format (ticker or zero-padded CIK), and notes name unsupported. Baseline 3, slight extra value justifies 4.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' with clear verb ('get profile'), resource ('US public company'), and scope. Example queries further reinforce purpose.

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

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

Description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and clearly states names are not supported, directing users to 'use resolve_entity first.' This provides clear when-to-use and when-to-avoid 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 destructiveHint=true and readOnlyHint=false. The description adds value by specifying the reason for deletion (e.g., clearing sensitive data) but does not cover edge cases like missing keys or side effects. Overall consistent and helpful.

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: two sentences with no redundant information. The purpose is front-loaded, and usage guidance follows immediately. 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 simple one-parameter tool with clear annotations and no output schema, the description is fully complete. It covers purpose, usage context, and related tools. 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?

The schema description coverage is 100% with the 'key' parameter already explained as 'Memory key to delete'. The tool description adds minimal extra meaning beyond stating 'by key', which is already implied. Baseline score applies.

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

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

The description clearly states the action ('delete') and the resource ('a previously stored memory by key'). It is specific and distinct from sibling tools like 'remember' and 'recall' by focusing on 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 provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with related tools ('remember' and 'recall'), offering clear context 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?

Discloses fetching, extraction, and output format beyond annotations. No contradiction with readOnlyHint or other annotations; adds context about the process.

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

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

Single paragraph, front-loaded with primary action, includes use cases compactly. 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?

Given simple schema, full coverage, and annotations, description covers purpose, process, output, and use cases. No missing critical information.

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 description adds little beyond schema. Mentions defaults (25, max 50) already in schema. No new semantics added.

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

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

Clearly states the verb 'generate' and the resource 'llms.txt file', specifying the purpose for AI crawlers. Distinguishes from siblings like ai_visibility_check by focusing on file generation.

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

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

Explicitly lists three use cases (client indexing, personal drafting, competitor auditing). Lacks explicit 'when not to use' but provides strong positive 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 mark the tool as safe (readOnly, idempotent, non-destructive). The description adds context about returned fields and the default behavior of returning only active subscriptions. Could mention pagination or limits, but overall sufficient.

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 concise sentences, front-loaded with the action and return fields. Every word adds value; no unnecessary information.

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

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

Given the annotations, high schema coverage, and no output schema, the description is fairly complete. It covers purpose, return values, and usage context. Could mention potential limits or edge cases, but not essential.

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

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

The schema covers the single parameter with a description, so baseline is 3. The description mentions active subscriptions but does not add extra meaning about the 'include_inactive' parameter beyond what the schema 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 uses a specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions'. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

The description provides explicit use cases: reviewing before adding more subscriptions and finding an ID to cancel. It implicitly suggests when not to use (if the goal is to subscribe or unsubscribe), but does not name alternatives explicitly.

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 rate limits (5 per identifier per day), cost (free), and quota impact (no tool-call quota usage). It also explains that feedback is read daily and affects roadmap. Annotations are neutral (no readOnly, etc.), so no contradiction. These behavioral details are 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 concise, front-loaded with the primary action, and every sentence adds value. It uses clear structure: purpose, usage guidance, behavioral notes. No redundancy.

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

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

Given the tool's simplicity (feedback submission) and lack of output schema, the description covers all necessary context: purpose, rate limits, cost, and content guidelines. It is complete for an AI agent to use the tool correctly.

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

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

Input schema coverage is 100% and parameter descriptions are already clear. The description adds minimal extra semantics (e.g., '1-2 sentences typical, 2000 chars max' and reiterating type meanings). It is adequate but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools which are primarily for querying or betting, making it easy for an AI agent to select this tool for feedback.

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 bug reports, feature requests, data gaps, or praise. It also instructs what to include (relate to Pipeworx tools/packs, avoid pasting end-user prompts) and what not to do. This helps the agent decide when this tool is appropriate 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 cover read-only, idempotent, non-destructive. Description adds that data is aggregated, no PII, and cached with specific TTL. No contradictions.

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

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

Concise, front-loaded purpose, but uses a running paragraph format. Slightly dense but efficient with 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 simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, caching, and privacy. Minor gap: no mention of output format, but acceptable given simplicity.

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

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

Schema covers the single parameter with enum and description. Description adds nuance about short vs long windows for different insights, going beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window, using specific verbs and distinguishing from siblings like ask_pipeworx or discover_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?

Explicitly lists three concrete use cases and explains window choices. Could be improved by noting when not to use, but sibling context is 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 discloses detailed behavioral traits: monotonicity violations, partition-sum checks, Jaccard similarity threshold (0.30), placeholder filter, fill check against CLOB depth, and the response structure. It goes well beyond the annotations (readOnly, openWorld, idempotent) to explain what the tool does internally and under what conditions results are actionable.

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 clear paragraphs and examples. While it is lengthy (~300 words), every sentence adds necessary detail for the tool's complexity. It front-loads the main purpose and modes, then provides deeper algorithmic context. Minor redundancy exists (e.g., 'event' mode explained twice), but overall effective.

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

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

Given the tool's complexity (multiple modes, algorithmic filtering, fill check), no output schema, and no missing aspects, the description is remarkably complete. It covers default behavior, parameter usage, algorithmic details, edge cases (placeholder filter, low similarity), and practical implications (do not trade if book edge is zero). It also references a sibling tool for additional use 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?

The input schema already has 100% description coverage for both parameters, so baseline is 3. The description adds value by explaining the default behavior (trending scan), providing example slugs and seed questions, specifying that full URLs are accepted, and clarifying the mode each parameter activates. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between the default trending scan, event mode, and topic mode, providing specific examples. It also references sibling tools for custom sizing, aiding differentiation.

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

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

The description provides explicit guidance on when to use each parameter: call with no args for trending scan, pass 'event' for a specific market (recommended), and pass 'topic' for cross-event scanning. It includes examples of valid inputs and warns when not to trade (when realizable edge is non-positive), directing users to 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 show readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral context: caching (1h KV-level), response diagnostics, edge calculations (net of slippage, Kelly caps), and a 24h-move warning. 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 lengthy but well-structured: overview, model families, response fields, knobs, caching. Every sentence adds unique information relevant to an agent's selection and invocation. Could be slightly more streamlined but appropriate 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, the description fully details response structure (by_segment, fed fields, diagnostics) and knobs (min_liquidity, max_spread_pp). Covers edge computation, filter logic, and segment-specific details, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, baseline 3. The description adds value beyond schema by explaining parameter interactions (e.g., min_partition_leg_kelly vs min_kelly) and contextualizing defaults (e.g., slippage_pp rationale). This enhances understanding.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifying three model families. It is distinct from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx-derived 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?

The description indicates the tool is built for 'what should I bet on today' and avoids paging hundreds of markets. However, it does not explicitly contrast with sibling tools or provide when-not-to-use guidance, missing a direct endorsement of alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds crucial behavioral context: snapshots are not written daily (gaps on cache-miss), data starts from snapshot enablement, decay computed from daily closes not intraday. 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 dense but somewhat long. It is front-loaded with the core question, but the response structure details could be more concise. Every sentence serves a purpose, though.

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

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

No output schema, so the description fully explains response fields (tracked, expired, snapshot_dates) with sub-fields. Covers data quality (gaps, decay computation, limits). Complete for this 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 covers both params with descriptions (100% coverage). The description adds practical context: defaults (14 days, '1wk'), clamps (2-30), and response structure that guides parameter effect. Adds value beyond schema.

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

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

The description uses a specific verb phrase 'Edge persistence and decay telemetry' and clearly states the resource (daily polymarket_edges snapshots). It answers a concrete question about edge longevity, distinguishing it from sibling tools like polymarket_edges which likely provide current edges only.

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 when to use: to understand edge age and decay vs. current edges. It mentions limits (60-day TTL, snapshotting start) but does not explicitly name alternatives like polymarket_edges. However, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, making the safety profile clear. The description adds value by explaining the two modes, the return fields (top_of_book, verdict, etc.), and the risk of partial basket fills converting arb into directional positions—beyond what annotations provide. 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 all-caps headings (REQUIRES, SINGLE-MARKET, BASKET) and a clear usage note. However, it is verbose (multiple paragraphs) and could be more concise. Every sentence adds value, but length detracts from 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?

Given the complexity (two modes, many return fields) and absence of an output schema, the description thoroughly explains what is returned for each mode, including verdict options and risk indicators (thin_legs, forced_directional_risk). It covers all necessary context for an agent to 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% (4 parameters fully described). The description adds meaning by explaining the dual interpretation of `side` and `size_usd` across modes, the requirement for either `market` or `event`, and the defaults. This goes beyond the schema descriptions, making the parameters more usable.

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It specifies the verb (check), resource (order-book depth), and scope (edge risk), and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a prerequisite check.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It provides context for both modes and warns about thin books and partial fills. However, it does not explicitly state when NOT to use or compare with alternatives beyond the named 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 already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds critical behavioral details: it discusses bet-shape equivalence, compatibility_warning scenarios (non-equivalent shapes or semantically unrelated events), temporal alignment, and counters for dropped comparisons. 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 dense but structured: it starts with core purpose, then systematically addresses modes, response format, and safety fields. Every sentence is informative 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 complexity (cross-venue comparison with compatibility checks, no output schema), the description is thorough. It explains all response fields (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and covers edge cases. This enables accurate invocation without needing additional documentation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the purpose of each parameter (e.g., topic as shortcut list, explicit overrides) and providing examples. It clarifies that topic auto-fetches matching events, which goes 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains when spreads are meaningful vs. not. This differentiates it from sibling tools like polymarket_arbitrage (single-venue) and polymarket_edges (within Polymarket).

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 guides when to use each mode: topic for 10 pre-mapped macros, or explicit tickers for custom pairings. It warns that most pre-mapped topics currently return compatibility warnings ('pre-mapped ≠ tradeable'), helping the agent set expectations and avoid misapplication.

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 scoping (by identifier) and pairing with related tools, going 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?

Three sentences covering core function, usage scenarios, and scope. No superfluous words; front-loaded with key behavior.

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 1 optional parameter and no output schema, description adequately covers behavior and use cases. Could explicitly mention return type or format, but not necessary for clarity.

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 property description. Description adds value by explaining behavior when key is omitted and giving example values.

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

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

Description uses specific verb 'retrieve' and resource 'value previously saved via remember', clearly states dual behavior (get value or list keys). Provides concrete examples and distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly states when to use ('look up context... without re-deriving') and gives common scenarios. Implicitly excludes uses better suited to 'remember' or 'forget', but lacks 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: return payload structure, filtering capabilities, mark_read behavior, and polling suitability. It does not contradict annotations and provides additional useful context.

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

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

The description is concise at 4-5 sentences, front-loaded with the main purpose, and every sentence adds value. No fluff or redundancy.

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

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

Given no output schema, the description adequately describes the return format (source, citation_uri, raw payload). It covers all key parameters and mentions an alternative access method, making it 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%, so each parameter has a description. The tool description adds value by explaining how to use parameters (e.g., 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)') and elaborates on mark_read behavior ('so the next call only shows newer ones'), enhancing understanding beyond the schema.

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

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

The description clearly states it 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts) and verb ('Pull'), and includes details about the return payload (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or ask_pipeworx.

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

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

The description explains when to use the tool: for polling recent alerts, with filtering by type and/or since, and managing read state via mark_read. It also mentions an alternative GET endpoint for scripts/dashboards, but does not explicitly contrast with siblings beyond that.

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 idempotentHint=true. Description adds context about data sources, fallback behavior, USPTO API sunset, and return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

Single paragraph but well-organized: usage patterns first, then fan-out behavior, then parameter details, then return structure, then sibling differentiation. Efficient but could be slightly more structured for 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?

For a complex tool with multiple data sources, fallback logic, and various input formats, the description covers all necessary aspects: what it does, how it works, parameter details, return structure, and alternative tool. No output schema, but description provides sufficient guidance.

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 three parameters have 100% schema description coverage. Description adds practical details: 'since' accepts ISO or relative shorthand with examples, 'value' accepts ticker or CIK, 'type' is only 'company'. Goes beyond the schema's own descriptions.

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

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

Description starts with concrete query examples ('What's new with X'), then defines the tool as a change feed for a company in a time window, fanning out to multiple sources. Explicitly distinguishes from sibling 'entity_profile' by stating when to use that instead.

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 usage patterns ('latest on Y', 'what happened to Z'), explains the fan-out and fallback logic (GDELT→GNews, USPTO soft-fail), and explicitly says 'Use entity_profile instead when you want the static profile regardless of window'.

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 value beyond annotations: describes persistence semantics (permanent for authenticated, 24-hour for anonymous), scoping by identifier, and pairing with recall/forget. No contradiction with annotations (idempotent, non-destructive write op).

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

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

Efficient three-sentence structure: purpose, usage, implementation details. Front-loaded with the core action. Every sentence serves a distinct function without redundancy.

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

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

For a simple two-param tool with no output schema, the description is fully complete: covers purpose, usage context, persistence details, and relationship to sibling tools. No gaps for an agent to misinterpret.

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

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

Schema descriptions already cover key and value basics (100% coverage). Description enhances with concrete key naming conventions (e.g., 'subject_property', 'target_ticker') and value examples, adding practical usage guidance beyond the schema.

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

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

The description clearly states the verb 'Save data' and the resource 'agent memory', with specific examples of what to store (ticker, address, preference). It distinguishes itself from siblings like 'recall' and 'forget' by explaining its role as the store operation.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. Also tells when not to use implicitly by pairing with recall/forget. Provides context on session persistence differences between authenticated and anonymous users.

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 true, and destructiveHint false. The description adds internal behavior details: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups' and mentions auto-disambiguation, providing 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?

The description is substantive but not overly long; it is front-loaded with examples and then provides systematic details. Every sentence adds value, though could be slightly more compact without losing information.

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

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

Without an output schema, the description explicitly details what is returned for each type, including citation URIs and auto-disambiguation. It covers both parameter semantics and behavioral context, making the tool self-contained for the 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?

Schema coverage is 100% with descriptions for both parameters. The description adds significant context: for 'type', it lists supported values and explains return formats (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug); for 'value', it provides examples and notes auto-disambiguation for company.

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 a user-spoken name to a canonical identifier, with specific examples ('What's the ticker for…') and supported types ('company', 'drug'). It distinguishes from sibling tools like 'compare_entities' and 'entity_profile' by focusing on ID lookup.

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 instructs to 'Use FIRST whenever you have a name but need an ID' and notes it replaces multiple manual lookups. It does not explicitly mention when not to use it or suggest alternative tools, but the guidance is strong.

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

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

Annotations already declare read-only, idempotent, and non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density per entity—transparent about method and output format.

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 primary action. Efficiently covers purpose, method, and output. Could be slightly more concise but 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 tool with 4 parameters, no output schema, and safety annotations, description covers input guidance, output format (ranked list with fields), and example use case. Missing error handling or limitations, but sufficient for selection.

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

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

Schema covers 100% of parameters. Description adds semantic value for 'entities' parameter: 'First entry treated as the subject for narrative; rest are competitors.' Also clarifies context parameter: 'Disambiguates common names.' This exceeds baseline 3.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking, and surfacing most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by specifying competitive AI-marketing audits.

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 usage context: 'Useful for competitive AI-marketing audits' with example question. Implicitly tells when to use but does not explicitly state when not to use or list alternatives beyond 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 indicate read-only, open-world, idempotent, non-destructive. Description adds crucial behavioral details: graceful degradation on partial failures, timing of bundlephobia first measurement (5-30s timeout), and the sources_failed field in output.

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

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

Description is dense but each sentence adds value. Slightly lengthy due to inclusion of return format and behavior details, but well-structured with purpose upfront and guidelines following.

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

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

No output schema, so description fully explains return values (summary block, advisory details, links, alternatives). Also covers error handling, ecosystem scope, and version timing, making it self-contained for agent understanding.

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 description for both parameters. Description adds value by clarifying version default behavior ('Defaults to the latest published version when omitted') and listing expected output fields which help infer parameter usage.

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

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

Description clearly states the composite check for npm packages, with a specific verb ('check') and resource ('npm package'). Distinguishes from sibling tools by noting NPM-only scope and mentioning alternative tools for other ecosystems.

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

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

Explicitly says when to use: agent queries about safety, popularity, size, or cost of adding a package. Also provides clear alternative for non-NPM ecosystems ('fall under deps.dev:version directly').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable details: embedding model (BGE-base-en), window size (500-char overlapping), character limit (200K chars) with truncation behavior, and output format (offsets, scores). 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 dense but clear sentences, each valuable. Front-loaded with purpose, then usage, then technical details. 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?

No output schema, but description fully explains expected return (top-N passages with offsets/scores). Covers limitations (truncation), algorithm, and pairing with another tool. Complete for a retrieval 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%, baseline is 3. The description adds value beyond schema by providing concrete query examples (e.g., 'supply-chain risk') and explaining the algorithm context, though it slightly duplicates 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) and resource (fetched record). It distinguishes from sibling tools like ask_pipeworx_grounded by focusing on internal retrieval.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt'. Also provides alternative pairing with ask_pipeworx_grounded, giving clear usage 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 idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description goes beyond by detailing side effects (returns new subscription ID), constraints (requires Pipeworx OAuth, rate limits for SMS, auto-disable for webhooks), and delivery behavior. 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 detailed but well-structured, with clear sections for purpose, prerequisites, supported types, and delivery channels. Every sentence adds value, though it could be slightly more concise. It earns a high score for efficiency given the complexity.

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

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

Given the tool's complexity (3 parameters, one nested, no output schema), the description covers all necessary aspects: purpose, usage, parameter details, constraints, and return value ('Returns the new subscription id'). It is fully sufficient for the agent to 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 by explaining each enum value for 'type', providing detailed examples for 'params' for all types, and describing delivery field constraints (e.g., phone verification, rate limits, webhook signing). This enhances the agent's understanding beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies the tool's function, distinguishing it from siblings like 'list_subscriptions' and 'unsubscribe'. It includes specific use cases and prerequisites.

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 detailed guidance on when to use each subscription type and prerequisites (e.g., OAuth account, phone verification). It lacks explicit 'when not to use' or comparison with alternative tools, but the context implies this tool is for creation only.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context that it returns structured example questions and that the tool is drawn from a live catalog. No contradictions.

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

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

The description is somewhat lengthy but front-loaded with common trigger phrases. Every sentence adds value, though a few words could be trimmed without losing meaning. The structure is clear and the most critical information comes first.

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 role as an onboarding entry point with no output schema, the description adequately explains the return format (category-bucketed examples with tool shapes) and usage patterns. It covers when to use it and how to focus the query, which is sufficient for an agent to get started.

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 'topic' parameter described as an optional focus area. The description adds meaning by listing example topics and explaining how to omit for a cross-category spread, which supplements 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 identifies the tool as the onboarding entry point for a new agent, listing multiple trigger phrases ('What can I ask Pipeworx?', 'give me ideas', 'getting started'). It specifies the return of category-bucketed example questions with tool+argument shapes, and distinguishes it from siblings like 'ask_pipeworx' by positioning it as the first tool to use.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments for full spread or with a topic parameter to focus. It does not explicitly state when not to use it, but 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?

Description adds ownership enforcement, soft-deletion, and historical availability via recent_alerts, going beyond annotations that only indicate idempotency and non-destructiveness.

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

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

Two sentences with key info front-loaded: action first, then ownership and effect details. No redundancy.

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

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

Given simple input schema and annotations, description covers purpose, behavioral nuances, and links to related tool (recent_alerts) for 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 has 100% coverage for the single parameter 'id', so description adds no extra meaning; 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 verb ('cancel') and resource ('subscription by id'), and distinguishes from siblings by specifying ownership enforcement and soft-deletion behavior.

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

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

Implies use case (cancel own subscription) and informs about soft-deletion, but does not explicitly state when to use alternatives like permanent deletion 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 provide readOnly, openWorld, idempotent hints. The description adds value by detailing the internal process (SEC EDGAR + XBRL), the verdict types, and that it replaces 4-6 calls, which informs the agent about cost and complexity. 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 examples and key information. Every sentence adds value, though it is somewhat lengthy. Still, it remains efficient and well-structured for the amount of context provided.

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

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

Despite lacking an output schema, the description fully explains the return format: verdict types, structured form, actual value with citation, and percent delta. All essential information for agent invocation is covered.

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 'claim' already has a schema description. The tool description goes beyond by providing concrete examples and specifying it accepts natural language, which enriches understanding of expected input format and content.

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 natural-language examples that clearly indicate the tool's purpose: claim verification. It specifies the domain (company-financial claims for public US companies) and distinguishes itself from siblings by stating it replaces multiple sequential calls, showing it's a specialized, efficient tool.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also defines the supported claim domain. While it doesn't list when not to use or name alternatives, the context is clear enough for the agent to decide.

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