Realestate

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

The description adds significant behavioral context beyond the annotations. It discloses the scoring mechanism (0-100), the default model and its free nature, the billing implication for Anthropic probing, and the return structure including per-model data and a combined view. This complements the readOnlyHint, openWorldHint, and idempotentHint 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 four sentences that are front-loaded with the core purpose. Every sentence adds value: stating the action, default model, optional key for Anthropic, return format, and use cases. No redundant information.

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

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

Given the tool's complexity, the description adequately covers return values since no output schema is provided. It details the per-model response fields (score, confidence, signals, raw_response) and a combined view, making it complete for an AI agent to understand the tool's output.

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 coverage is 100%, but the description adds value beyond the schema. For example, it explains that the default model is Workers AI Llama-3.3-70b (free), that an API key is needed for Anthropic, and that the context parameter helps disambiguate entities. These details aid in correct 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?

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on visibility scoring across multiple models.

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

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

The description provides context for when to use the tool, such as AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains how to probe additional models by providing an API key. However, it does not explicitly state when not to use the tool or compare it directly to sibling tools like scan_competitor_ai_presence.

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, so the tool is clearly safe and idempotent. The description adds value by explaining it routes questions to a vast tool set, returns structured answers with stable citation URIs, and is fast. This amplifies the annotation information without contradicting 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?

The description is well-structured with front-loaded purpose and clear use-case paragraphs, but it is verbose (e.g., long list of domains). It could be shortened without losing clarity. The use of examples and alternative names adds value but increases length.

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

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

The tool is complex (4,770 sub-tools) yet the description covers input format, examples, use cases, alternatives, and output structure (structured answer with citation URIs). No output schema exists, but the description adequately fills that gap. Annotations and context signals are fully leveraged.

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%; all parameters are described in the schema (including aliases). The description reinforces that the question is natural language and accepts multiple aliases, but this adds minimal incremental meaning beyond the schema. Given high coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool is for answering factual questions using authoritative structured data from 4,770 tools across 1,241 sources. It lists specific domains (SEC filings, FDA drugs, etc.) and provides concrete examples, making the purpose unmistakable. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, addressing 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 extensive guidance: it explicitly prefers this tool over web search, gives usage triggers (phrases like 'what is', 'look up', 'current'), explains when to use alternatives (ask_pipeworx_grounded for citation confidence, deep_research for broad queries), and includes examples. This covers 'when', 'when not', and 'alternatives' thoroughly.

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?

Despite annotations already indicating readOnly, openWorld, idempotent, and non-destructive, the description adds critical behavioral detail: refusal patterns with specific reasons, evidence extraction, and the extra LLM call cost. 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?

Well-structured with key purpose first, followed by behavioral details and usage guidance. Slightly verbose in listing refusal reasons but maintains clarity. 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 no output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. Covers all necessary context for high-stakes use.

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

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

All 6 parameters are aliases for 'question' with 100% schema coverage, but the description explicitly lists the aliases and clarifies they are interchangeable, adding convenience 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 clearly defines it as a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing it from the sibling tool 'ask_pipeworx' by noting the extra LLM call cost and use cases for quote-requiring answers.

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

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

Provides explicit when-to-use guidance (answers to be quoted, cited, or acted on with no fact invention) and when-not-to-use (prefer ask_pipeworx for casual lookups), along with specific domains like financial, legal, medical.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing resolver contract (confidence levels, alternative markets), parent event extraction, news fallback mechanisms, safety checks (low-confidence, closed markets, wide spreads), and cancellation rule risk. This comprehensive disclosure ensures the agent understands all behavioral traits and caveats.

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

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

The description is lengthy with multiple paragraphs and detailed examples. While well-structured with headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it could be more concise. Some redundancy exists (e.g., repeating 'one call' theme). The front-loading of the summary is good, but the overall length may overwhelm agents seeking quick understanding.

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, absence of an output schema, and high schema coverage, the description is remarkably complete. It covers input formats, processing steps, output structure (market, analysis, evidence), edge cases (low-confidence, closed markets, wide spreads), and even cancellation rules. No gaps remain for an agent to confidently use the tool.

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

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

The description adds substantial meaning beyond the input schema. For 'market', it clarifies it accepts slug, URL, or question text. For 'depth', it explains 'quick' vs 'thorough' with evidence source counts. For 'include_raw', it describes when to use true (needing full payloads) and default behavior. This enriches the agent's understanding of each parameter.

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

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

The description clearly states the tool's purpose as researching a Polymarket bet by pulling Pipeworx data in one call, specifies input types (slug, URL, question text), and outlines the output (evidence packet + market-vs-model comparison). This verb-resource pair is highly specific and distinguishes it from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage' which focus on different aspects.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also lists classifiers and fan-out examples. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, slightly lowering the score.

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

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

Annotations indicate readOnly, openWorld, idempotent. Description adds rich behavioral details: uses latest SEC data, handles off-calendar fiscal years, returns sorted results, and provides citation URIs. No contradictions with annotations.

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

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

Description is comprehensive but front-loaded with examples. Every sentence adds value (examples, data sources, sorting). Could be slightly more concise but remains efficient.

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

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

Despite no output schema, description explains return format (paired data + citation URIs), sorting, and data sources for both entity types. Complete for a comparison tool with two distinct modes.

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. Description adds value by clarifying data sources for each type (company: financials; drug: adverse events) and sorting behavior, which goes beyond schema constraints.

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 'side-by-side comparison of 2-5 companies or drugs in ONE parallel call' with specific verb 'compare' and resource 'entities'. It distinguishes from sibling tools by noting it replaces 8-15 sequential lookups and should be preferred over them. Example queries are provided.

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' and gives example triggers like 'X vs Y'. However, it does not explicitly state when not to use the tool, 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?

Discloses account requirement, paid tier for 'thorough' depth, parallel decomposition process, return format with gaps[], expected duration (15-60s), limitations for topics not in catalog, and that it never invents information. 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?

Well-structured with critical info (account) first, then purpose, methodology, use cases, alternatives, and limitations. Every sentence adds unique 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?

Thoroughly covers all aspects: prerequisites, behavior, return format (findings packet with citations and gaps[]), expected latency, and when results may be empty. No output schema, so description fully compensates.

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

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

Schema coverage is 100%, and description adds meaning by explaining the depth enum values (quick=3, standard=5, thorough=8) and clarifying that question is for broad/multi-part natural language queries.

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 performs grounded multi-source research across 1241 structured data sources, distinct from open-web search and siblings like ask_pipeworx. Provides examples of appropriate queries.

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

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

Explicitly tells when to use this tool (broad/multi-part questions over structured data) and when not (single lookups, breaking news, colloquial current events), naming alternatives like ask_pipeworx and noting account/plan requirements.

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 that it returns '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 provides concrete behavioral context beyond the annotations.

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

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

The description is front-loaded with the core purpose and usage, then details the return format. It is slightly verbose but every sentence serves a clear function. Could be tightened slightly but remains 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?

The tool has 6 parameters (1 required), no output schema, and a large set of siblings. The description covers the critical context: when to use it, what it returns, and that it includes schemas for direct invocation. This is sufficient for the agent to understand its role.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema for the parameters. It mentions aliases but those are already documented in the schema properties.

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

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

The description uses specific language ('Find tools by describing the data or task') and lists numerous domains (SEC filings, FDA drugs, etc.). It distinguishes this tool from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'.

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 when you need to browse, search, look up, or discover what tools exist for: ...' and provides a clear directive to call it first among many tools. This guides the agent away from directly fetching a single answer.

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, destructiveHint. The description adds significant behavioral details: parallel fan-out across multiple sources, soft-fail for patents, fallback for news (GDELT→GNews), and specific return structure. No contradictions.

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

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

The description is dense but well-structured, front-loading with example queries and then listing outputs and sources. Each sentence adds value, though it could be slightly more streamlined. It is concise given the amount of information conveyed.

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

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

Given the tool's complexity (multiple sources, fallback behaviors, sunset notice), the description provides a thorough overview of what the tool returns and its limitations. No output schema exists, so the description adequately 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% and already describes the two parameters (type enum, value string). The description reinforces this and adds context that names are not supported and suggest pre-processing with resolve_entity, adding marginal 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 clearly states the tool's purpose: generating a full cross-source profile of a US public company. It provides example queries and lists the data sources and return fields, distinguishing it from siblings that perform single-source 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 explicitly advises when to use this tool ('ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view') and when not to (names not supported, suggests using resolve_entity first). It provides clear context and 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 destructive and idempotent; description adds context about clearing sensitive data. Could mention permanence or behavior on non-existent keys.

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 focused sentences: purpose, usage, companion tools. 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?

Covers purpose and usage for a simple operation. Minor omission: what happens if key doesn't exist. Otherwise complete.

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

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

Schema covers key description fully (100%), so baseline 3. Description adds no extra insight beyond 'by key'.

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', specific resource 'memory', and method 'by key'. Distinguishes from siblings by naming '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?

Explicit when-to-use scenarios: stale context, task done, clear sensitive data. Also mentions pairing with related tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown format. 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 well-structured with a lead sentence stating purpose, followed by mechanism and use cases. It is concise (three sentences) without unnecessary words, though it could be slightly more streamlined.

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 explains the output format (single text blob). It covers input, process, and output adequately. Missing error handling or edge cases, but sufficient for a straightforward tool.

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

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

Schema coverage is 100% with descriptions for both parameters (url and max_links). The description mentions fetching a page (implicitly requiring url) but does not add new semantic meaning beyond the schema. 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 generates an llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt 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?

The description provides explicit use cases: getting a client's site indexed by AI, drafting llms.txt for own project, or auditing competitor visibility. It does not explicitly state when not to use, but the context is clear and covers common 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds default behavior (active only) and return structure.

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

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

Two sentences, no waste. First sentence defines purpose and return, second gives usage guidance. Front-loaded and clear.

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

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

Given simplicity (one optional param, no nested objects, no output schema), the description fully covers purpose, usage, and return. Annotations handle behavioral traits.

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 description does not add meaning beyond the schema's parameter description. Baseline 3 applies.

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

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

Clear verb 'list' + 'subscriptions' with caller scope. Differentiates from sibling tools subscribe/unsubscribe by being a read-only list operation. Explicitly states return fields.

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

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

States when to use: before adding more subscriptions or to find an id to cancel. Implicitly suggests using subscribe/unsubscribe for other actions.

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 important behavioral traits beyond annotations: it is free, does not count against tool-call quota, and is rate-limited to 5 per identifier per day. It also explains that the team reads digests daily and feedback affects roadmap. No contradiction with annotations.

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

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

The description is concise and well-structured. It opens with the purpose, then gives usage guidelines, and ends with constraints. Every sentence adds value without repetition.

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

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

Given no output schema, the description adequately explains what happens with feedback (digests read daily, affects roadmap). It covers feedback types, usage instructions, and constraints, making it complete for its 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%, but the description adds significant meaning: it explains each enum option (bug, feature, data_gap, praise, other) and provides guidance on message content (be specific, 1-2 sentences, 2000 chars max). For the context parameter, it clarifies it is optional and describes its fields.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools like ask_pipeworx or deep_research by being a feedback channel.

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

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

The description explicitly lists when to use the tool (for bugs, feature requests, data gaps, praise) and provides guidance on what to include (describe in terms of tools/packs, avoid pasting end-user prompt). However, it does not explicitly state when not to use it, though the 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?

Adds detail beyond annotations: source (CF analytics-engine), no PII, caching intervals. Annotations already indicate safety (readOnlyHint, idempotentHint). 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?

Three sentences: what it does, three use cases, behavioral notes. No wasted words, front-loaded with 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?

For a simple read tool with one param, description covers return fields, caching, and use cases. Lacks output schema but not essential given simplicity.

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

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

Schema coverage 100%, description adds value by explaining window effect (hot vs steady-state demand). Exceeds baseline of 3.

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

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

Clear verb 'Returns' and resource 'top tools, top packs, and total call volume'. Distinguishes from sibling tools like 'discover_tools' by focusing on trending/usage 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 specific use cases and explains window behavior for different needs. No explicit when-not, but context is clear for a read-only trend tool.

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 substantial behavioral context: the semantic anchor (Jaccard similarity), partition filter, fill check logic, 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 very detailed and well-structured, front-loading key information. However, it is verbose and includes technical details (e.g., fill check, similarity thresholds) that could be condensed or moved to examples. Still, it earns credit for organization.

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, internal algorithms, fill check), the description is complete. It explains all modes, mechanisms, and response structure. Since no output schema exists, the description compensates fully by detailing the response fields and trade recommendations.

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% (both parameters have descriptions). The description adds considerable value beyond schema by explaining the modes, giving examples, and detailing how parameters affect behavior. Baseline 3 is exceeded due to rich additional 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific explanations, making it unambiguous and distinct 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?

The description explicitly tells when to use each mode: no args for trending_scan, event slug for single-event, topic for cross-event. It explains why cross-event mode catches patterns single-event misses. However, it does not compare with sibling tools like polymarket_edges or polymarket_edge_tracker, so a perfect 5 is not given.

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

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

The description extensively discloses behavioral traits beyond annotations: caching (1h KV cached), model details (lognormal barrier, GDELT signal, partition_overround mechanics), response structure (by_segment, diagnostics), and edge calculation (net of slippage, Kelly fraction caps). 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 the main purpose but is very long and dense, mixing model details, parameters, and response structure without clear sections. While content-rich, it could be more structured for easy 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 no output schema, the description adequately covers return fields (edge_pp_net, kelly_fraction, liquidity, spread, diagnostics) and explains why segments may be empty. It is comprehensive but could be slightly more detailed on response 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?

All 9 parameters have descriptions in the schema (100% coverage), and the description adds practical guidance (e.g., setting min_liquidity to 5000 to avoid thin-book issues, explaining slippage assumptions). This adds value beyond the schema's baseline.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, targeting a 'what should I bet on today' use case. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which might offer alternative analyses.

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

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

The description implies the tool is for discovering edge opportunities and explains knobs for filtering, but it lacks explicit guidance on when to use this tool versus siblings like polymarket_arbitrage or polymarket_edge_tracker. Usage is implied rather than overtly stated.

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

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

The description adds significant behavioral details beyond the annotations (which already indicate read-only, idempotent, non-destructive). It discloses reliance on daily snapshots, how decay is computed (from daily closes), the 60-day TTL bound, and response structure. 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 efficiently structured: starts with purpose, then arguments, then detailed response format, ending with limitations. Every sentence contributes meaningful information 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 thoroughly documents the return fields (tracked, expired, snapshot_dates) and their subfields (first_seen, trend, decay_pp_per_day, etc.), plus explains limitations like TTL and data gaps. This makes the tool fully understandable in isolation.

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

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

The input schema has 100% coverage with parameter descriptions. The description adds value by stating default values and maximum for 'days' and default for 'window', placing them in context. This goes beyond the schema without being overly repetitive.

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

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

The description clearly states the tool's function: providing edge persistence and decay telemetry from daily snapshots. It explains the core question ('how long has this edge existed and is it shrinking?') and distinguishes it from sibling polymarket_edges by focusing on historical trends rather than current 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 implies when to use the tool (to understand edge persistence over time) through its purpose statement and rationale about fresh vs. old edges. It also provides LIMITS about data depth. However, it does not explicitly contrast with alternatives or 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds rich behavioral context: it reveals it walks the order-book ladder, returns fill details, warns about thin books and directional risk, and explains the two modes. 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 and well-structured with clear sections for modes and warnings. It could be slightly more concise, but every sentence adds necessary information for correct tool 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 no output schema, the description comprehensively lists all relevant output fields for both modes, including verdict, profit_usd, thin_legs, forced_directional_risk, etc. It completely covers the complex tool 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%, but the description adds significant meaning: it explains single-market vs basket parameter usage, default side logic, interpretation of size_usd for buys/sells/basket, and mentions defaults and clamps. It 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 clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, listing specific outputs. It differentiates from sibling tools like polymarket_arbitrage by explicitly stating when to use this tool before acting on trade 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?

The description 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 overrun not capturable, partial fills lead to directional risk). It 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?

The description extensively discloses behavioral traits beyond annotations: compatibility_warning conditions (non-equivalent bet shapes, unrelated events), temporal alignment checks, skipped cross-type/subtype counters, and the rarity of real spreads. This far exceeds the readOnlyHint annotation.

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 verbose but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value given the tool's complexity, though some redundancy exists (e.g., repeating the shortcut list). It is appropriately front-loaded with purpose and modes.

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

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

Despite no output schema, the description comprehensively explains the response fields (leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, skipped counters) and edge cases. It covers both normal operation and failure scenarios, making it self-contained for an AI 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. The description adds value by explaining how topic interacts with explicit overrides (overrides the mapped side), which is not evident from the schema alone. However, the description does not significantly expand on the parameter types or constraints beyond the schema, so a baseline of 3 with a slight bump to 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: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit event specifiers) and explains the signal detection logic, setting it apart 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?

Explicit usage guidance is provided: use topic mode for 10 pre-mapped macro shortcuts, or explicit mode for custom pairings. It warns that most pre-mapped topics currently return compatibility_warning, and explains when spreads may be invalid (e.g., temporal misalignment). No explicit when-not-to-use statement, but the safety fields effectively indicate conditions to avoid.

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 annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value beyond annotations by specifying the data source (MLIT's 不動産情報ライブラリ) and the optional _apiKey parameter, providing useful behavioral context without contradicting 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 two sentences long with no wasted words. It is front-loaded with the core purpose, then provides a concrete usage example. Every sentence serves a clear function: stating the action/resource/source and giving practical usage guidance. This is highly efficient.

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

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

For a simple list tool with low complexity, two parameters, no output schema, and strong annotations, the description covers all necessary context: it states what is returned (cities/wards with codes), how to invoke it (prefecture name or code), and the optional API key. The example reinforces understanding. No additional information appears needed.

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

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

Schema coverage is 100% with both parameters (_apiKey and prefecture) having descriptions. The description reinforces the prefecture parameter's format (name or code) but does not add new meaning beyond what the schema provides. Baseline 3 is appropriate as the description does not compensate for any missing schema details.

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

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

The description clearly states the tool's action ('List'), the resource ('cities/wards with 5-digit municipality codes'), and the context ('within a Japanese prefecture'). It explicitly differentiates from its sibling realestate_transactions by showing how it resolves a city code for that tool, 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?

The description provides explicit usage guidance: 'Use to resolve a city code for realestate_transactions' and explains how to pass the prefecture parameter (name or 2-digit code). However, it does not explicitly state when not to use this tool or mention alternatives, leaving a minor gap in exclusion criteria.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral context by detailing the data source, coverage, and return fields (type, district, trade price, etc.). It does not contradict annotations and provides useful extra information 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 a single concise paragraph that front-loads the most important information (prefer over search, data source, filters). It efficiently conveys key details without unnecessary verbosity. Slight improvement could be making the filter list more scannable, but it's highly functional.

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 8 parameters, no output schema, and moderate complexity, the description covers the data source, coverage period, available filters, and output fields. It lacks explicit details on pagination, ordering, or response format, but the limit parameter and field listing provide adequate context. The description is complete enough for an agent to use effectively.

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

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

Schema coverage is 100%, with all parameters described. The description adds overall context about filters and coverage but does not significantly enhance per-parameter meaning beyond the schema. It groups filters meaningfully but doesn't add new details for individual parameters.

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

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

The description clearly states the tool provides Japanese real estate transaction prices from MLIT's database. It specifies the data source, coverage (2005-Q3 onward), and types of prices (transaction and agreed). It also distinguishes itself from web search, making the tool's unique value explicit.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' for property/land prices in Japanese cities, providing clear when-to-use guidance. It also lists filtering options (prefecture, city code, station code, year+quarter) and mentions coverage dates, helping the agent decide when to invoke this tool over alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and clarifies the listing behavior when key is omitted. No contradictions.

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

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

Three well-structured sentences. First sentence defines core function, second gives usage context, third provides scoping and pairing. No wasted words, front-loaded with essential information.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description is thorough. It covers dual mode, scoping, and relationships with siblings. Could optionally mention return format, but not necessary given the simplicity.

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

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

Schema coverage is 100% with a clear description of the key parameter. The tool description adds meaningful context by explaining the dual behavior and providing concrete examples (ticker, address, notes) beyond the schema.

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

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

Description clearly states the dual function: retrieve a specific value by key or list all keys when omitted. It provides concrete examples of use cases and explicitly distinguishes from sibling tools '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 says when to use (look up stored context) and contrasts with re-deriving from scratch. Mentions pairing with 'remember' and 'forget', giving a clear usage pattern. Could be slightly more explicit about when not to use, but it's well-contextualized.

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 states that setting mark_read:true flags events as read, modifying state. This contradicts the annotation 'readOnlyHint: true', which implies no write operations. Per the scoring rule, description contradicting annotations results in a score of 1. Annotation Contradiction set to true.

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 with 4 sentences, front-loaded with the purpose, and each 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 5 parameters with full schema coverage and no output schema, the description covers what returns (source, citation_uri, payload), filtering options, and read flag behavior. It also provides an alternative access method. Missing details like error handling, but annotations (openWorldHint, idempotentHint) reduce the burden.

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 by explaining the effect of mark_read and the ISO format for since, and examples for type. It goes beyond the schema descriptions, especially for mark_read's behavioral impact.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts. It uses specific verbs ('Pull', 'Returns') and describes the content (source, citation_uri, payload), distinguishing it from siblings like list_subscriptions which manage subscriptions themselves.

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 filtering by type and since, using mark_read to control read state, and mentions polling works fine. It also gives an alternative REST endpoint for scripts/dashboards. However, it does not explicitly compare to other tools or 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context such as fan-out strategy, fallback mechanism, soft-failure for USPTO, and output structure (changes grouped by source, total_changes, pipeworx 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 concise yet comprehensive. It is front-loaded with example queries, each sentence adds distinct value (purpose, usage, fallback, output format), and there is no redundancy. The length is appropriate for 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 has 3 required parameters with full schema coverage and no output schema, the description adequately covers the return structure (changes, total_changes, citation URIs) and the behavior of each source. It is complete enough for an agent to invoke and process results 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?

With 100% schema coverage, the description still adds meaning by explaining the acceptable formats for 'since' (ISO date or relative shorthand), explaining 'value' accepts ticker or CIK, and clarifying that 'type' only supports 'company'. Examples like 'AAPL' and '0000320193' are provided.

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 change feed for a company over a recent window, fanning out to multiple sources like SEC EDGAR, GDELT/GNews, and USPTO. It clearly distinguishes itself from the sibling tool 'entity_profile' by contrasting dynamic changes vs. static profile.

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

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

The description provides explicit when-to-use guidance with example queries and contrasts with 'entity_profile' for static needs. It also details fallback behavior (GDELT preferred, GNews when rate-limited or 5xx) and gives specific date format examples ('7d', '30d', etc.).

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 and destructiveHint=false. The description adds context about scoping by identifier, session persistence (24 hours vs permanent), and the fact that data is stored as key-value pairs. This goes beyond the annotations but could more explicitly mention idempotency.

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 the main purpose and is generally concise, though slightly longer than necessary. Every 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?

Despite no output schema, the description fully explains what happens when data is stored (scoped key-value, persistence rules). It covers all needed context for the tool's simple functionality.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds meaningful context on how to use the parameters (e.g., examples like 'subject_property', 'target_ticker') and clarifies that value can be any text.

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

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

The description uses specific verbs ('save', 'store') and resources ('data', 'key-value pair') to clearly state the tool's purpose. It distinguishes itself from sibling tools by mentioning pairing with 'recall' and 'forget'.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and provides context on persistence based on authentication status. It also mentions complementary tools for retrieval and deletion.

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

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

Annotations indicate safe read-only operation. Description adds that it cascades through multiple lookup endpoints, replacing several manual steps. Discloses return format and citation URIs.

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

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

Front-loaded with examples, but slightly long. Every sentence is useful; could be tightened but still effective.

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

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

Thoroughly covers two entity types, input formats, internal process, and return values. No output schema, but description provides adequate return info.

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

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

Schema coverage is 100%. Description adds meaning by explaining valid inputs for 'value' per type and elaborating on 'type' enum behavior 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 resolves a name to a canonical ID, with specific examples like 'ticker for...'. It distinguishes from sibling tools like compare_entities and entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides context for each supported type (company, drug) with input/output details.

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, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized, along with return details (score, confidence, signal density). 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 a single paragraph of four sentences. The first sentence front-loads the main purpose. It is efficient but could be better structured (e.g., bullet points for return 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?

Given the moderate complexity (multi-entity comparison, multiple models, optional API key), the description covers the process, output, parameter roles, and use case. It does not mention rate limits or dependencies on ai_visibility_check, but is largely 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%, each parameter has a clear description. The description adds that 'entities' first entry is treated as subject, but this is minor. No additional parameter meaning beyond schema is provided.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource ('AI visibility'). It distinguishes from siblings like ai_visibility_check (single entity) and uses competitive audit context.

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

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

The description gives a use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use it or list alternatives. It implicitly suggests using ai_visibility_check for single entity probes, but lacks direct exclusion criteria.

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 readOnly etc., but description adds critical behavior: bundlephobia measurement delay (5-30s), graceful degradation with sources_failed field, and that it returns a summary block. 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 well-structured and front-loaded with core purpose. Every sentence is informative; could be slightly trimmed but remains effective.

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

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

No output schema; description compensates by listing summary fields, per-advisory detail, links, alternative versions, and error handling. Comprehensive for a composite 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 covers both parameters (100% coverage). Description adds context: package accepts scoped names like @types/node, version defaults to latest. Also describes return structure, adding 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?

Clearly states the tool is a composite check for deciding to add an npm package, fanning out across deps.dev and bundlephobia. Distinguishes from siblings by specifying NPM-only 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 tells when to use: whenever an agent asks about safety/popularity/size or what adding a package costs. Also notes limitations: NPM ecosystem only, and for other ecosystems use deps.dev:version directly. Mentions graceful degradation for partial failures.

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 safety traits. The description adds significant detail: embedding model, window size, character cap with truncation warning, and that passages include offsets for verification. Adds valuable 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?

Three sentences total: purpose, usage context, technical details. All sentences earn their place with no redundancy. Front-loaded with the core action.

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

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

Covers purpose, when to use, technical constraints, and pairing with sibling. No output schema needed as description explains return structure (passages with offsets and scores). Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and description repeats most schema descriptions verbatim. Adds minimal extra meaning (e.g., examples for query). Baseline 3 is appropriate as it does not significantly enhance understanding 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 starts with 'Semantic search INSIDE a fetched record', clearly stating the verb and resource. It distinguishes itself by noting that it works with previously fetched data and pairs with a sibling tool, making its purpose distinct.

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 when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, providing clear context. Lacks explicit when-not scenarios, but 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?

The description is extremely transparent about behavior beyond annotations: it details return type, prerequisites, delivery channel constraints (sms verification, 10/day cap, webhook auto-disable after 10 failures, etc.). Annotations are present and consistent (readOnly=false, destructive=false, idempotentHint=true may be slightly off but not contradicted).

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

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

The description is well-structured and front-loaded with the core purpose and return value. It efficiently packs a lot of information without redundancy. However, it is somewhat long; every sentence earns its place, but a slightly tighter version might be more concise.

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

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

Given the tool's complexity (3 params, nested objects, multiple types, delivery channels), the description is comprehensively complete. It covers prerequisites, type-specific parameters, delivery constraints, and return value. The output schema is absent, but the description states it returns the subscription id. The sibling tools list provides context for alternatives.

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 substantial extra meaning: it gives concrete examples for each type (e.g., sec_8k: {ticker, items}), explains each delivery channel in detail (webhook HMAC verification, sms cap), and provides constraints (e.g., webhook rejects localhost). This goes well beyond the schema descriptions.

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

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

The description clearly states the purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions the return value (subscription id). It distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description provides explicit when-to-use guidance, including prerequisites (Pipeworx OAuth account, not for anonymous/BYO), and details when each subscription type is appropriate (e.g., sec_8k for SEC filings matching ticker and item codes). It also hints at when not to use (e.g., if you need to list or cancel, use siblings). The context from sibling tools reinforces this.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that the tool returns example questions with exact tool+argument shapes, and explains the behavior with and without the topic argument. No contradictions.

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

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

The description is a single paragraph that front-loads key phrases and lists all categories. Every sentence adds value, but it is slightly verbose. Could be more concise 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?

For a single optional parameter and no output schema, the description fully explains the return format (category-bucketed example questions) and usage scenarios. It also references sibling tools, making it complete for an onboarding tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that omitting topic gives a full spread and listing example focus areas. This helps the agent decide how to use the optional parameter.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx by explicitly saying to use this first when unsure what Pipeworx can do.

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 context: use this first when you don't know about Pipeworx, and learn how to call meta-tools. It also explains when to omit or provide the topic parameter. However, it does not list specific alternatives or 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?

The description adds significant behavioral context beyond annotations: it explains that subscriptions are deactivated (not deleted) and historical events remain via 'recent_alerts'. Annotations (destructiveHint: false, idempotentHint: true) are consistent and reinforced.

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

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

Two concise sentences with no fluff. The first sentence states the core action, the second provides ownership and persistence details. 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?

Given the tool's simplicity (single parameter, no output schema), the description covers all necessary aspects: action, ownership, side effect (deactivation vs deletion), and reference to historical data availability. It is fully self-contained.

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

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

Schema description coverage is 100%, with the 'id' parameter already described as a UUID from 'subscribe'. The description adds no new parameter-level information, meeting the baseline expectation.

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

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

The description clearly states the tool cancels a subscription by ID using a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the cancel action and ownership enforcement.

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 ownership enforcement, implying it should be used only for the user's own subscriptions. It provides clear context but does not explicitly name alternative tools or conditions for non-use.

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

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

Annotations already convey safety (readOnly, idempotent). Description adds valuable behavioral details: returns specific verdict types, structured form, citation link, and percent delta, and explains it replaces multiple lookup steps.

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

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

Well-structured: trigger phrases first, then use case, scope, output details, and efficiency benefit. Every sentence serves a purpose; 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 one parameter and no output schema, the description fully explains the domain, output format, and scope. Covers all needed context for an 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 coverage is 100%, so baseline 3. Description adds context beyond schema: clarifies that the claim is natural-language and provides example phrases. Adds slight extra meaning.

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

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

The description uses specific verb-resource pairing ('verify claims') and provides multiple natural-language trigger phrases. It clearly distinguishes from siblings by noting it replaces 4-6 sequential calls.

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

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

Explicitly states when to use ('whenever the agent needs to check factual correctness'). Adds domain limitation (company-financial claims). No explicit alternatives or when-not-to, but context is clear.

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