Isbn

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the per-model return structure (score, confidence, signals, raw_response) and combined view, plus the cost implication of using Anthropic. This goes beyond what annotations provide.

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

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

The description is three sentences, front-loaded with action and key details. Every sentence adds value (purpose, usage, return structure). 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?

The tool has 4 parameters and no output schema, so the description should cover return values. It does so by specifying per-model and combined view fields. However, it does not fully detail the combined view structure or edge cases (e.g., what happens without API key). Still 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% (all parameters described). The description adds useful context: the default model is free, the '_apiKey' enables Anthropic probing with direct billing, and 'context' helps disambiguate. This extra information justifies a score above baseline 3.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It specifies default and optional models. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' or 'entity_profile', which could be related.

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

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

The description mentions use cases like AI-marketing audits and brand checks, providing context for when to use. However, it does not specify when not to use, nor does it contrast with alternatives such as '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 cover read-only, idempotent, non-destructive behavior. Description adds context about routing to 4,552 tools, returning structured answers with stable citation URIs, and being fast. No contradictions.

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

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

The description is somewhat verbose (~150 words) but front-loaded with key guidance. It is well-structured: preference statement, capabilities, examples, then escalation paths. Minor redundancy but earns a 4.

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

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

Given the tool's complexity (routing to diverse sources), the description covers purpose, usage, output format (citations), examples, and alternatives. No output schema but description sufficiently explains what the user gets.

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 having descriptions. The description reinforces that the question is natural language but does not add new parameter-level meaning beyond the examples. 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 routes questions to structured data sources and returns answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and explicitly says 'PREFER OVER WEB SEARCH'.

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 (factual questions, authoritative data), when-not (breaking news still covered but suggests other tools for hallucination-resistant or broad queries), and names alternatives with specific 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 indicate read-only, open-world, idempotent, non-destructive. Description adds that it makes an extra LLM call, returns fields like refusal_reason, and explicitly refuses with reasons (not_in_source, etc.). 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 front-loaded with key purpose and usage, then details. Slightly long but each sentence provides useful information—no wasted words. Structurally sound.

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

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

Given no output schema, the description thoroughly explains return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and refusal modes. Combined with annotations, it provides complete context for safe, high-stakes usage.

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

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

Schema description coverage is 100% (baseline 3), but description only restates that the parameter accepts natural language and lists aliases without adding new meaning beyond the schema. Adequate but not enhanced.

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

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

Clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from 'ask_pipeworx' by specifying that it extracts answers only from tool results, preventing fabrication. The verb and resource (extract grounded answer) are specific.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. Also tells when to prefer the alternative: 'prefer ask_pipeworx for casual lookups' due to extra cost. 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing behavior: market resolution, classification, fan-out, response shapes, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread warnings), and resolution-rule risk. 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 comprehensive but extremely verbose (almost 2000 characters). While front-loaded with the main action, it dives into excessive detail about classifiers, fan-out examples, response shapes, and edge cases. Could be more concise by grouping or shortening examples.

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

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

Without an output schema, the description thoroughly explains all aspects of the response: result.market fields, result.analysis, evidence structure, resolver contract, parent event extractor, news fallback, and safety/edge-case handling. It leaves no ambiguity about what the tool returns.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema fields: it explains the three formats for 'market', the default and effect of 'depth' (quick vs thorough), and the purpose of 'include_raw' (summary vs full payload). This fully compensates for the lack of additional details in 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: researching a Polymarket bet by pulling Pipeworx data. It specifies the input as a slug, URL, or question text. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, which may have overlapping use cases.

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

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

The description provides clear usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives concrete examples of when to invoke the tool, but does not mention when not to use it or alternatives among siblings.

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

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

Annotations indicate readOnly, idempotent, and openWorld hints. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions with annotations.

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

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

The description is concise yet dense with information, using common query patterns for front-loading. Every sentence adds value without redundancy.

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

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

For a tool with no output schema and moderate complexity (two entity types, multiple data sources, sorting, citations), the description provides complete context on behavior, return format, and efficiency gains. It fully compensates for the missing output schema.

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

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

Schema coverage is 100% with clear descriptions. The description enriches the meaning by explaining the type enum with data sources and the values parameter with examples and constraints (e.g., tickers vs drug names, min/max items).

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data sources and sorting. It distinguishes from siblings like entity_profile by explicitly noting it replaces multiple sequential lookups.

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

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

The description explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, and provides example queries. However, it does not explicitly mention when not to use it or suggest specific alternatives like entity_profile for single entities.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=true, indicating safe, non-destructive behavior. The description adds constraints about the 978 prefix and check digit recomputation, providing useful behavioral detail 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 concise with two clear sentences. It front-loads the primary action and then provides specific rules. No superfluous information is present.

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

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

The description covers the core functionality and constraints, but it does not mention error handling (e.g., invalid ISBNs or unsupported prefixes) or specify the output format. Given the simple tool and presence of annotations, it is nearly 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?

The parameter 'isbn' has 100% schema coverage with a minimal description. The tool description does not add additional meaning or constraints for the parameter itself (e.g., expected format, length, or validation rules), so it meets but does not exceed the baseline.

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

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

The description clearly states the tool converts between ISBN-10 and ISBN-13 and recalculates the check digit. It is specific about the conversion direction and prefix rule. However, it does not explicitly differentiate from the sibling tool 'validate_isbn', which performs validation rather than conversion.

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

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

The description implies the tool is for converting ISBN formats, but it lacks explicit guidance on when to use it versus alternatives like 'validate_isbn'. There is no mention of when not to use it or prerequisites, so the agent must infer usage context.

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

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

Adds many behavioral details beyond annotations: account required, paid plan for thorough, 15-60s latency, returns gaps[] for unanswered facets, never invents answers. Annotations already show readOnly, openWorld, idempotent, non-destructive, and description aligns.

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?

Long but every sentence is purposeful: account requirement, usage guidance, capabilities, output format, limitations. Front-loaded with critical requirement. Slightly verbose but justified for complexity.

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

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

Completely describes purpose, behavior, output, prerequisites, and sibling differentiation. No output schema exists, but description compensates by naming the result format (findings packet with evidence, confidence, source, citation).

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

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

Schema has 100% coverage but description adds context: depth maps to explicit facet counts (quick=3, standard=5, thorough=8) and explains that broad questions are fine. Adds value beyond schema enumeration.

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 structured data sources, decomposes questions into facets, and runs parallel tool calls. Distinguishes from siblings like ask_pipeworx by scope and data type.

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 best for broad/multi-part questions, single lookups should use ask_pipeworx, breaking news should use ask_pipeworx, and notes account requirements including a paid plan for 'thorough' depth.

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 valuable context about the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' 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?

Front-loaded with purpose, then lists domains, then explains return value and usage order. Slightly long but every sentence adds value. Could be more concise in listing domains but effective overall.

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

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

No output schema, but description fully explains what is returned (tool names, descriptions, schemas with examples) and how to use it as an entry point. Covers all necessary aspects for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds aliases for 'query' (q, task, search, description) but these are also listed in the schema. The examples provide concrete use cases, adding marginal value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from sibling tools by positioning it as the first call to browse available options.

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

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

Explicitly advises when to use: 'when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set.' No ambiguity.

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 soft-fail for USPTO (PatentsView API sunset), return specifics (up to 5 filings, latest 10-K data, GDELT→GNews fallback). Annotations already cover readOnly/idempotent/non-destructive, so description adds value beyond them.

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

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

Dense but efficient; front-loaded with examples and key usage instruction. Slightly long but all content earns its place. Could be slightly more structured.

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

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

No output schema, yet description details all return components (cik, company_name, recent_filings with URIs, fundamentals with specifics, patents, news, LEI). Comprehensive for a 2-param 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 has 100% coverage with descriptions. Description adds context: type limited to 'company', value must be ticker or zero-padded CIK, names not supported. Provides example formats.

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 explicitly states tool provides a 'full cross-source profile of a US public company in ONE parallel call', listing sources and return fields. Differentiates from sibling tools like resolve_entity by clarifying name handling.

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?

Clearly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and instructs to use resolve_entity first if only a name is available.

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 destructiveHint=true and idempotentHint=true. Description 'Delete' aligns with destructive nature and adds behavioral nuance about clearing sensitive data, providing value beyond annotations.

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

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

Two sentences, no wasted words. Action is front-loaded and every sentence adds value.

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

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

For a simple single-parameter destructive tool with no output schema, the description covers purpose, usage, and relationships completely.

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?

Parameters are fully covered in schema (100%), and description adds no extra meaning to the 'key' parameter beyond what schema already provides.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It references sibling tools 'remember' and 'recall', distinguishing its purpose from them.

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

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

Description provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' While it doesn't explicitly state when not to use, the context is clear and pairs well with siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds process details (fetches page, extracts title/description/links, emits standard format) that enrich understanding. However, it omits potential failure modes or rate limits, but given the annotations, this is sufficient.

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

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

The description is three sentences with perfect front-loading: first sentence states purpose and output format, second explains process, third lists use cases. No fluff, every sentence earns its place.

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

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

Despite no output schema, the description explicitly states the output format ('single text blob ready to drop at site-root/llms.txt'). For a simple tool with two parameters and clear annotations, this provides complete context for use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra semantics by stating the default (25) and max (50) for max_links, and the context of fetching the page. This goes beyond the schema and justifies a score above the 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?

The description clearly states the verb 'generate' and the resource 'llms.txt file', and distinguishes it from sibling tools which are unrelated (e.g., bet_research, deep_research). It specifies the output format and use cases, 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 lists three explicit use cases (indexing client site, drafting own project, auditing competitor). While it does not explicitly state when not to use or alternatives, the sibling list shows no competing tool, so the guidance is adequate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing return fields and parameter behavior, but doesn't disclose other behavioral traits like auth needs or rate limits. 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 two sentences with no filler. It efficiently conveys the action, return fields, and usage guidance. Every sentence earns its place.

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

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

Given the simple tool with one optional parameter and no output schema, the description covers the purpose, return fields, and usage context. It ties to sibling tools by mentioning reviewing subscriptions before adding more and finding an ID to cancel.

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 the parameter `include_inactive` already fully described. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description starts with a specific verb+resource: 'List the caller's active subscriptions.' It clearly states what the tool does and lists the returned fields. It is easily distinguishable from siblings like subscribe and unsubscribe.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool and implies when not to. It could be improved by directly naming sibling tools, but the context is clear.

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

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

Annotations are neutral, and the description adds critical behavioral details: rate limit of 5 per identifier per day, free usage (no quota impact), and that team reads digests daily affecting 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 well-structured: purpose first, then usage scenarios, then behavioral constraints. Every sentence adds unique information without redundancy. It is appropriately sized for a feedback tool.

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

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

Given the tool's simplicity (no output schema needed), the description covers all necessary aspects: purpose, when to use, how to format feedback, rate limits, and impact. Nothing is missing for an agent to correctly invoke it.

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

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

Schema coverage is 100%, but the description adds value by explaining the meaning of each type with examples, advising specificity in the message, and clarifying that context should reference tools/packs. This enhances the schema's documentation.

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

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

The description clearly states the tool is for reporting issues, missing features, or praise. It uses specific verbs ('Tell', 'broken, missing, or needs to exist') and distinguishes itself from sibling tools by focusing on feedback rather than queries or research.

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

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

The description explicitly lists when to use each feedback type (bug, feature, data_gap, praise) and provides negative guidance ('don't paste the end-user's prompt'). It also instructs to describe issues in terms of tools/packs, setting it apart from other tools that answer questions or perform 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 adds significant behavioral context beyond annotations: data source (CF analytics-engine), privacy (no PII), caching (5min-1h depending on window), and content (pack, tool, count). Annotations already include readOnlyHint, openWorldHint, idempotentHint, destructiveHint; no contradiction.

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

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

The description is concise: three main sentences plus a bulleted list of use cases. It front-loads the return value, then provides usage context, then implementation details. No redundant or extraneous content.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers essential aspects: return value (top tools, packs, volume), data source, privacy, caching, and use cases. It does not specify the exact format of the return, but given the tool's simplicity, it is sufficiently 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% and already describes the window parameter with enum and meaning. The description adds value by explaining the trade-off between windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which aids parameter selection 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 returns top tools, top packs, and total call volume over a time window, with specific verb 'returns' and resource 'top tools, top packs, call volume'. It distinguishes from siblings by focusing on trending data and providing three concrete use cases.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases), providing clear guidance on when to use. However, it does not mention when not to use or compare directly with sibling tools like discover_tools, so it's not a full 5.

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

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

Annotations declare read-only, idempotent, non-destructive. The description adds substantial behavioral details: algorithms (monotonicity violations, partition checks), filtering (Jaccard similarity threshold, placeholder detection), response structure, and fill check. No contradictions with annotations.

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

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

The description is long but well-structured, with front-loaded purpose and subsequent details on modes, algorithms, and response. Every sentence adds value given the tool's complexity, though it could be slightly more concise.

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

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

Despite lacking an output schema, the description fully explains the response structure (opportunities[], partition_check), fill check, and references sibling tools for sizing. With 2 optional params and no required fields, it provides all necessary information for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds meaningful context: explains the difference between event and topic modes, provides examples of values (e.g., 'fed-decision-may-2026'), and describes the behavior triggered by each parameter. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then distinguishes three modes (no args, event, topic) which differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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 when to use each mode: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`.' It recommends event mode for specific markets, explains cross-event mode catches patterns single-event misses, and directs custom sizing to polymarket_fill_risk. Also warns about fill check conditions.

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 elaborates extensively on the tool's behavior: caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge calculation details (Kelly fractions, slippage, 24h move warning), and explanations of filters. All these add value beyond the annotations, which already declare it read-only and idempotent.

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 and densely packed with technical details. While every sentence seems informative, it could be more concise. The structure is front-loaded with purpose but rambles into model families and mathematical formulas. It earns a 3 for being adequate but not optimally 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 (9 parameters, no output schema, multi-segment logic), the description is remarkably complete. It covers response structure, caching, filter skips, edge interpretations, and even reasons for excluding Fed bets. Agents have enough context to understand and invoke the tool correctly.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by explaining the interplay and practical effects of parameters like min_partition_leg_kelly (how it applies to partition arbs) and the tradeable-edge filters. For most parameters, the description reinforces schema info, but it adds nuance.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is specifically built for the 'what should I bet on today' use case, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 the usage context ('Built for what should I bet on today') and explains tradeable-edge knobs that guide when to use this tool. However, it does not explicitly state when not to use it or compare to alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: explains that snapshots are written on cache-miss, describes the response structure (tracked, expired, snapshot_dates), and details computed fields like trend and decay_pp_per_day. It also discloses data gaps and history depth limits.

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

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

The description is relatively long but well-structured with clear sections for tracked, expired, and snapshot_dates output, and a LIMITS note. It is front-loaded with the core purpose. While it could be slightly more concise, every sentence adds necessary 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?

With no output schema, the description fully explains the return values: tracked (with time-series, first_seen, trend, decay), expired (with lifespan_days), and snapshot_dates. It also covers edge cases like data gaps and history depth limits. This is comprehensive for a complex tool.

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

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

Both parameters are already documented in the schema (100% coverage). The description adds value by explaining 'days' as lookback with default and max, and 'window' as snapshot family with default '1wk'. It provides context about snapshot writing behavior, enriching the meaning beyond the schema alone.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' built from snapshots, and answers the specific question of how long an edge has existed and whether it's shrinking. This distinguishes it from sibling tools like polymarket_edges which likely provide current edges only.

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

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

The description gives clear context on when to use (to check edge persistence vs freshness) and includes a concrete example differentiating a fresh wide edge from an old one. It also mentions limits like 60-day TTL. However, it does not explicitly state when not to use or name alternative tools.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds behavioral context: ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp), and the risk of theoretical overround not being capturable on thin books.

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 clear sections (SINGLE-MARKET, BASKET) and front-loaded purpose. However, the description is somewhat verbose and could be trimmed without losing essential guidance.

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

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

No output schema exists, yet the description enumerates all key return fields (top_of_book, vwap, slippage, shares_filled, verdict, etc.) and explains the two modes sufficiently for agent decision-making.

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

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

Schema coverage is 100% but description adds meaning: default size_usd (1000), clamp range, interpretation of size_usd for buys vs sells, and basket mode side auto-detection. Provides context beyond schema.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes from siblings by recommending usage before polymarket_arbitrage and polymarket_edges trades.

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?

Specifies required parameters (market or event), default side logic, and explicit when-to-use conditions: before arbitrage signals or trades above ~$500. Also warns about risks of partial fills converting arb into unhedged positions.

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: it explains safety fields, compatibility conditions, temporal alignment, and skipped leg counters. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. However, it is lengthy and some dense sentences could be trimmed without losing essential info.

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

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

Given no output schema, the description thoroughly explains the response format, safety fields, and edge cases like temporal misalignment. It covers all necessary context for a tool with 3 optional parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing topic shortcuts, providing examples for explicit parameters, and explaining override behavior, thus enhancing semantic understanding.

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

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

The description clearly states the tool's purpose as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and details two specific modes.

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

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

The description provides explicit guidance on when to use each mode (topic vs explicit), and warns that most pre-mapped topics may not yield tradeable spreads. It also explains compatibility_warning conditions to help interpret results, but does not directly contrast with siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds scoping to identifier and dual behavior (retrieve vs list). Could mention what happens if key not found, but overall fine.

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 wasted words. Front-loaded with action, then provides usage context. Excellent structure.

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

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

Complete explanation for a simple read-only tool with no output schema. Covers purpose, usage, examples, scope, and sibling relationships.

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% with description of key parameter. Description adds context on omission behavior and typical key values, going 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?

Clear verb ('Retrieve' or 'list') and resource ('value previously saved via remember'). Distinguishes from siblings by cross-referencing remember and forget. No ambiguity.

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

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

Explicitly states when to use ('look up context the agent stored earlier') with concrete examples, and implies when not (no need to re-derive). Scoping and pairing instructions provided.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds value by explaining the mark_read parameter behavior and that polling is safe, which goes 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 concise with no unnecessary words. It front-loads the main action and efficiently conveys key details in a few sentences. Every sentence earns its place.

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

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

The tool is a simple read-only operation with full schema coverage. The description explains return values (source, citation_uri, payload) and even provides an alternative access method. For a tool with no output schema, this is complete and actionable.

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 meaningful context: example filter value ('sec_8k'), explanation of mark_read behavior, and mention of ISO timestamp format for 'since'. This increases clarity beyond the schema alone.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource (fired events/alerts) and the verb (pull/returns). It distinguishes from sibling tools like list_subscriptions or subscribe by focusing on alerts rather than subscription management.

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

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

The description implies when to use (to get recent alerts) and provides context that polling works fine, including an alternative method via direct URL. However, it does not explicitly say when not to use this tool versus siblings, which would make it a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains PatentsView API sunset and soft-fail, and describes the structured return format. 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 front-loaded with natural language examples, then provides core purpose, fallback logic, parameter details, return format, and sibling differentiation. Every sentence adds value, though it could be slightly more concise. It is well-structured and easy to parse.

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

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

With 3 required parameters, no output schema, and moderate complexity, the description covers everything: purpose, parameter details, behavioral fallbacks, return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), and sibling differentiation. No missing information for an AI agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: for type, it notes 'Only "company" supported today'; for since, it provides examples and relative shorthand explanation, plus suggests '30d' or '1m' for typical monitoring; for value, it explains ticker or CIK formats. These enrich parameter understanding.

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

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

The description starts with multiple natural language query examples, then explicitly states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes itself from the sibling tool entity_profile, which handles static profiles. This is a specific verb+resource combination with clear differentiation.

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

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

The description provides explicit when-to-use context through query examples and explains fallback behavior (GDELT to GNews). It also explicitly states when not to use it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This provides both usage context and clear 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 provide basic hints (idempotent=true, not destructive). Description adds valuable context: scoped by identifier, persistence for authenticated users vs 24h for anonymous. Does not detail overwrite behavior or limits, but sufficient.

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

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

Concise, each sentence serves a purpose. Front-loaded with main action. No redundant or vague statements. Efficient for an AI agent to parse.

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

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

For a simple key-value store tool, description covers purpose, usage, scope, lifetime, and relationship with siblings. No output schema needed; function is straightforward.

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 clear descriptions. Description adds example values for key and elaborates on value types (findings, addresses, etc.), providing extra guidance beyond schema.

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

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

Description clearly states the tool saves data the agent will need later, with explicit verbs 'save' and 'reuse'. It distinguishes from siblings by mentioning '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?

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides examples like resolved ticker, target address. Also mentions pairing with recall and forget.

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 internal cascading through endpoints. Annotations (readOnlyHint, idempotentHint) are consistent. Description adds return value details (ticker, CIK, RxCUI, 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?

Well-structured, front-loaded with examples, then purpose, usage, and detailed supported types. Every sentence adds value, though could be slightly more concise.

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

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

Given complexity and no output schema, description fully explains return values, supported types, input variations, and internal cascading. Annotations cover safety aspects.

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

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

Schema has 100% description coverage, but description adds significant detail: accepted input formats (ticker, CIK, name for company; brand/generic for drug) and output types.

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

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

Description clearly states verb 'resolve' and resource 'name to identifier', and differentiates from siblings like entity_profile and compare_entities. It gives example queries and explains the output.

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' and notes it replaces 2-3 manual lookups. Does not explicitly list when not to use, but context makes it clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check, returns ranked list with score/confidence/signal density, and probes each entity—fully disclosing behavior.

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: purpose, mechanism, use case. No fluff, 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?

Given no output schema, description explicitly lists return fields (score, confidence, signal density). Explains probe method and competitive context, fully covering agent needs.

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

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

Schema coverage is 100%, so description need not repeat. It adds value by explaining entities' first entry as 'subject' and models' supported values ('workers-ai' default, 'anthropic' with 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?

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes from sibling tools like ai_visibility_check (single entity).

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 a concrete use case ('competitive AI-marketing audits') and implies when to use vs ai_visibility_check. However, it lacks explicit when-not-to-use or mention of alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds critical behavior: bundlephobia first measurement can take 5-30s, and partial failures list sources_failed. Also details output structure (summary block, advisories, links, alternatives). 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 a single coherent paragraph that flows logically: purpose, usage, return details, limitations, fallback. Every sentence adds value. Could be slightly more structured with bullets, but not wasteful.

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

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

With no output schema, description fully explains return format (summary block fields, per-advisory, links, alternative versions). Covers ecosystem scope, failure handling, timing caveats. This is complete for an agent to understand what to expect and how to handle results.

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

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

Schema coverage is 100% with clear descriptions for package (including scoped packages) and version (defaults to latest). Description adds extra context about scoped packages and version default, which is helpful but not essential given schema covers basics. Baseline 3, additional value lifts 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 composite check for npm packages, specifying the two sources (deps.dev and bundlephobia) and the types of information retrieved. It differentiates from sibling tools by being specific to npm ecosystem and offering a one-call comprehensive check.

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

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

Explicitly tells when to use: when agent asks about safety, popularity, size of an npm package. Also delineates what not to use for (other ecosystems) and points to alternative (deps.dev:version directly). Mentions graceful degradation for partial failures, aiding appropriate invocation.

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. The description adds significant behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output includes offsets and scores. 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?

Every sentence earns its place. The description is concise (~100 words), front-loaded with purpose, and well-structured: use case, pairing, technical details.

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 output format (top-N passages with offsets and scores). It covers model, windowing, cap, and truncation behavior. Complete for a complex tool.

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

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

All parameters have schema descriptions (100% coverage). The description enhances with examples for query, default 5 for limit, and max chars for text. Adds meaning beyond schema.

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

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

The description clearly states the tool does semantic search inside a fetched record, using specific verb 'search' and resource 'inside a fetched record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with other tools that fetch or research.

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

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

The description explains when to use ('when the record is too big to cram into the prompt') and pairs with another tool. It doesn't explicitly state when not to use, but context is clear from sibling tools. A bit more guidance on alternatives would improve 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 indicate idempotent and non-destructive mutations. The description adds rich behavioral details: return of subscription ID, account requirements, type-specific filtering, delivery channels with rate limits (SMS 10/day), webhook signing and auto-disable on failures. 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 core purpose and returns value. It uses clear structure with categories (Supported types, Delivery channels). While dense, it could be slightly more concise, but every sentence adds useful information.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers the return value, prerequisites, and detailed behavior. It does not explicitly mention error handling but provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains each subscription type with examples (e.g., 'sec_8k' with item codes, 'fred_series' with series_id), details delivery channel behaviors (always-on feed, templated email, per-event SMS, HMAC-signed webhook with auto-disable). This goes well 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 action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is specific and distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

Provides detailed context on when to use (requires Pipeworx OAuth account, not for anonymous/BYO) and how to configure types and delivery. Does not explicitly name alternatives but the context is clear enough for an agent to differentiate from sibling tools.

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

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

Description adds significant behavioral details beyond annotations: it returns category-bucketed example questions with tool+argument shapes. Annotations already indicate readonly, idempotent, open-world, non-destructive; description aligns and adds specificity.

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

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

The description is moderately long but well-structured, starting with common user queries, then explaining output format and usage. Every sentence adds value, though could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains return values (category-bucketed examples with tool shapes), covers the optional parameter, and positions the tool within the broader toolset (sibling tools). No gaps.

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

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

Schema coverage is 100% with a good description of the optional topic parameter. The description adds example categories and explains the effect of omitting vs. providing a topic, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point for agents to discover what questions to ask Pipeworx, listing specific example queries and distinguishing it from sibling tools by advising to use it first.

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 guides when to use (when you don't know what Pipeworx can do) and how to call (no args for full spread, topic for focus). Lacks explicit when-not-to-use but provides strong contextual 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 adds behavioral details beyond annotations: ownership enforcement and deactivation vs deletion. Annotations already cover destructiveness and idempotency, so this is complementary.

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

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

Two sentences, front-loaded with the main action, every sentence provides essential information with no waste.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently covers purpose, constraints, side effects, and availability of historical data.

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

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

Schema coverage is 100% with description of 'id'. The tool description adds context ('by id' and 'returned by subscribe') without repeating schema, adding value.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('subscription by id'), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It provides context on when to use the tool (ownership enforcement, cancellation of own subscriptions) but does not explicitly exclude usage for others or mention alternatives.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds significant behavioral context: supported claim types (company-financial), data sources (SEC EDGAR + XBRL), and return format (verdict types, structured form, actual value with citation, percent delta). 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 front-loaded with examples and clear purpose. It is slightly verbose but every sentence adds value, detailing scope and output. Could be tightened slightly, but overall well-structured.

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

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

Given the single parameter with full schema coverage and no output schema, the description is complete. It covers purpose, usage, scope, limitations (v1 only financial), and return details, leaving no gaps for an agent to make incorrect assumptions.

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 a detailed parameter description. The tool description enriches this by providing example inputs and clarifying the natural-language nature of the claim. It adds value beyond the schema without redundancy.

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 like 'verify', 'confirm or refute', and specifies the resource (natural-language claim verification against authoritative sources). It clearly distinguishes from siblings like 'deep_research' by scoping to company-financial claims and mentioning it replaces multiple 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?

The description explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and explains what it replaces (4-6 sequential calls). It provides clear context for usage but does not explicitly state when not to use or list alternatives beyond the sibling list.

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 and idempotentHint. The description adds that it automatically detects ISBN format, ignores hyphens/spaces, and uses specific check digit algorithms, which are behavioral details beyond annotations.

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

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

Two sentences: first states the core function with algorithm details in parentheses, second adds input formatting and scope. No filler, front-loaded.

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

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

For a simple single-parameter validation tool with full annotations, the description covers purpose, behavior, and limitations completely. No output schema needed as return value is implied (valid/invalid).

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

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

The single parameter 'isbn' is fully described in schema (100% coverage). The description adds that hyphens/spaces are ignored, which provides useful input formatting guidance beyond the schema's example.

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

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

The description clearly states the tool validates ISBN-10 and ISBN-13, detecting format and check digit, and distinguishes itself from sibling tools like convert_isbn by stating it validates the number, not the book.

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 that validation is keyless and offline, and clarifies it only checks the number's validity, not the book's existence. While not explicitly contrasting with siblings, it gives enough info for appropriate use.

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