Ulid

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds cost implications for Anthropic calls, the default model, and the return structure (per-model score, confidence, signals, raw_response + combined view). This provides useful behavioral context not covered by 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, well-structured paragraph that front-loads the action and purpose. Every sentence adds value, with no redundancy or filler.

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

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

Given the tool has 4 parameters, no output schema, and moderate complexity, the description adequately explains inputs, return structure, and use cases. It compensates for the lack of output schema by describing the return fields.

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: explains the 'entity' parameter scope, the default for 'models', the purpose of '_apiKey', and how 'context' helps disambiguate. This enriches the schema definitions.

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 explicitly distinguishes the tool's purpose from siblings like 'scan_competitor_ai_presence' by focusing on brand/product audits with per-model scoring.

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 the tool is useful (AI-marketing audits, pre-launch brand checks, competitive monitoring) and includes usage details like the default model and optional Anthropic key. It doesn't mention alternative tools, but the scenarios are 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it routes to the right tool among 5,269 sources and returns structured answers with citation URIs, plus notes it's 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 long but front-loaded with the key directive. It is well-structured with examples and usage guidance, earning its sentences.

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 and lack of output schema, the description is very complete: it covers purpose, usage, alternatives, examples, and behavioral context.

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

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

Schema coverage is 100%, so description doesn't need to add much. The description provides examples and context for what constitutes a good question, adding value beyond the schema's alias listing.

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 factual questions about current/historical data, routing to many sources, and distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research. It uses specific verbs and resources.

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 'PREFER OVER WEB SEARCH' and provides criteria for when to use this tool vs alternatives. Also states 'START HERE for most questions' and gives examples of when to step up to other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the beta nature, that routing improvements may be active, that it currently matches the stable version, and that it is a full working router. 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 about 4-5 sentences, front-loaded with purpose, then explains current state and usage. Every sentence adds value with no redundancy. A slightly more structured format could improve, but it is efficient.

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

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

Given the complexity of a universal router with 5,269 tools, the description adequately covers purpose, relation to sibling, experimental nature, current behavior, and fallback. No output schema exists, but the description mentions same response shape. Could include more on how to interpret outputs, but complete enough for an experimental 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 clear parameter descriptions explaining that all six parameters are aliases for the same 'question' string. The description adds no additional parameter-specific semantics beyond stating the tool takes the same arguments as ask_pipeworx, which is covered by 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 beta version of ask_pipeworx, identical in functionality and arguments, with experimental routing improvements. It distinguishes itself from the stable sibling by being the 'experimental edge' and explicitly notes that it currently matches the stable version since no candidate is active.

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: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells when to use it and implicitly contrasts with the stable ask_pipeworx, which is a sibling 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, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds meaningful context: the extraction process, refusal reasons (not_in_source, no_tool_match, etc.), and the one extra LLM call cost. No contradictions; the description complements annotations well.

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 reasonably concise with a front-loaded main purpose, though it includes a bullet list of refusal reasons that could be streamlined. Every sentence adds value, and the structure (purpose, comparison, return format) is clear. Minor room for tightening, but overall effective.

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

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

Given no output schema, the description fully explains the return format for both success and failure, including exact field names. It covers the tool's complexity (6 params, any question) with appropriate detail about behavior, failure modes, and cost. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (question and aliases). The description adds no additional meaning beyond restating 'Your question in natural language,' which is already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb 'extracts the answer using ONLY what the tool result contains,' distinguishes from its sibling 'ask_pipeworx' by noting the extra cost and use case, and contrasts with casual 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups.' Additionally, explains the cost tradeoff, enabling informed decision-making.

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 exceptionally details behavioral traits beyond annotations: resolver contract, parent event extractor, news fallback fields, safety short-circuits, closed market handling, wide spread warnings, and cancellation rule parsing. It adds critical context that annotations (readOnly, idempotent) do not cover.

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 purpose and usage, but is very verbose (multiple paragraphs). While structured with section headers, it could be more concise. Every section earns its place, but the length may overwhelm agents.

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 (classifiers, fan-outs, response shapes), the description covers all aspects: inputs, outputs, edge cases, safety mechanisms, and market nuances. No output schema exists, so the detailed description of response fields compensates fully.

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 significant meaning: explains market accepts slug/URL/question text, depth enum with defaults, include_raw with response size impact. Examples in schema further clarify 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), distinguishing from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides examples of fan-outs and response shapes, but does not explicitly state when not to use 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it explains that for 'company' it pulls latest 10-K data and handles off-calendar fiscal years, for 'drug' it pulls FAERS data, results are sorted by primary metric, and returns paired data with citation URIs. This adds significant value beyond annotations, but could still detail the response format more.

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 highly efficient: it starts with example trigger phrases, states the core function, provides usage guidelines, and explains data sources—all in a few well-structured sentences. 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?

Given no output schema, the description adequately covers return values ('paired data + pipeworx:// citation URIs') and sorting behavior. It also addresses the tool's efficiency benefit. The tool's complexity is low, and the description covers all essential aspects for an agent to use it correctly.

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

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

Schema description coverage is 100%, and the description enriches it significantly by detailing the enum values (company vs drug) with specific data sources, explaining the values array with examples and constraints (2–5 items), and adding context about the underlying data (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 'compare', 'rank', and 'side-by-side comparison' and clearly identifies the resource (2–5 companies or drugs). It distinguishes itself from sibling tools like sequential single-pack 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 states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. However, it does not explicitly mention when not to use the tool or list alternatives beyond the sequential lookups.

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 strong annotations (readOnly, openWorld, idempotent, non-destructive), description adds significant behavioral details: parallel decomposition, gap reporting, contradictions, hop field, semantic excerpting, expected response times (15-90s). 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: begins with critical account requirement, then core functionality, then use cases, then detailed behavior. Each sentence adds value; slight redundancy in mentioning 'never invented' and contradictions separately but overall efficient.

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

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

Without an output schema, description comprehensively covers return format (findings with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field) and edge cases (breaking news, large records). Deeply completes the context for agent 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%, baseline 3. Description adds meaning: explains depth enum (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+iterative+contradictions) and clarifies 'question' accepts broad/multi-part naturally.

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

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

Description clearly states it does grounded multi-source research across 1374 structured data sources in one call. It distinguishes itself from siblings like 'ask_pipeworx' for single lookups and notes it is not open-web search, 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?

Explicit guidelines: requires account (free via GitHub), paid for 'thorough' depth. When to use: broad/multi-part structured questions. When not: use 'ask_pipeworx' for single lookup or breaking current news. Provides clear alternatives and prerequisites.

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

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

Annotations provide readOnlyHint and idempotentHint. Description adds behavior: returns top-N tools with full schemas and examples, 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?

Two efficient sentences plus a list. Front-loaded with purpose. Could tighten domain list 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?

No output schema, but description fully specifies return value: tool names, descriptions, schemas. Sufficient 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. Description mentions aliases and natural language usage but adds little beyond schema examples.

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?

Explicitly states 'Find tools by describing the data or task' and lists specific domains. Clearly distinguishes from siblings by being the discovery tool for all other tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' — clear context but no explicit 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?

Describes specific behaviors beyond annotations: patent data may soft-fail after May 2025, fans out across multiple sources, returns specific fields. Annotations already indicate read-only, idempotent, not destructive, so description adds context about edge cases.

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

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

Single paragraph but front-loaded with example queries and key usage guidance. Efficiently packs details about data sources and return fields without excessive verbosity.

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 2 parameters fully described, no output schema, but description enumerates all returned fields (cik, recent_filings, fundamentals, patents, news, LEI). Covers edge cases (patent API sunset). Complete for a complex tool.

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

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

Schema description coverage is 100%, but description adds examples and clarifies that value can be ticker or CIK, and names are not allowed. Provides additional context not in 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 provides a 'full cross-source profile of a US public company' and includes example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from siblings by emphasizing this tool should be preferred over chaining multiple lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view' and mentions that names are not supported, advising to 'use resolve_entity first if you only have a name'.

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 aligns with annotations (destructiveHint=true) by stating 'delete'. Adds context about usage scenarios but does not detail side effects beyond what annotations imply. A minor gap is not explicitly stating irreversibility.

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 action and resource, then usage guidelines. 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 only one required parameter and no output schema, the description covers the tool's purpose, usage conditions, and relationship to siblings comprehensively.

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

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

Schema coverage is 100% with a description for key. Description does not add further meaning beyond the schema's 'Memory key to delete'. 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?

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall'.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also advises 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard markdown. This surpasses the bare annotations and gives the agent a clear model of tool 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?

The description is extremely concise: two sentences for functionality and one for use cases. Every sentence adds value, front-loaded with purpose. 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 simplicity (2 params, no output schema), the description covers all relevant aspects: what it does, how it works (fetch, extract, emit), output format, and use cases. No gaps remain.

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 already clear parameter descriptions. The description mentions URL and max_links but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, using specific verbs ('generate', 'fetches', 'extracts', 'emits') and resource ('llms.txt file'). It distinguishes from siblings like 'ai_visibility_check' by focusing on file generation rather than checking crawl status.

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 use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It does not provide explicit when-not-to-use or alternatives, but the use cases are clear and the context is helpful for tool selection.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds useful behavioral context about the output format (Crockford Base32, 26 chars, time-encoded), which goes beyond the annotations without contradiction.

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

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

Two sentences with no filler. The first sentence states the action and resource, the second adds key format details. Every word 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 simplicity (one optional param, no output schema), the description is mostly complete. It describes input and output format implicitly, but could explicitly state that the return value is an array of strings for clarity.

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

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

Schema coverage is 100% with a clear description of the `count` parameter. The description does not add additional meaning beyond what the schema already provides, so it meets the baseline.

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

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

The description clearly states the tool generates ULIDs and explains what a ULID is (26-char Crockford Base32, time-encoded first 10 chars). It distinguishes itself from the sibling `parse_ulid` by focusing on 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 implies usage for generating unique IDs but does not provide explicit guidance on when to use this tool versus alternatives like `parse_ulid` or other generation tools. No exclusions or conditions are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by detailing the return fields and typical use, enhancing agent understanding of safe 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?

Two sentences: first conveys core purpose and output, second provides actionable usage guidance. No unnecessary words.

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

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

For a simple listing tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. Slightly lacking in explaining edge cases like empty results, but still complete enough.

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

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

Input schema has one optional boolean parameter with description; schema coverage is 100%. Description does not need to add parameter details since the schema already suffices.

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

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

Clearly states 'List the caller's active subscriptions' with a specific verb and resource, and enumerates return fields. Distinguishes from sibling tools 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?

Explicitly advises using it to review existing subscriptions before adding more or to find an ID to cancel. Lacks explicit when-not guidance, 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.

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context that validation and extraction are performed offline, and discloses the exact outputs (timestamp and random component), which is 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 two sentences long, front-loading the key action and outputs. Every word contributes meaning with no redundancy or filler.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool does, its inputs, and its context (keyless, offline). An agent has sufficient information to correctly select and invoke 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?

Schema coverage is 100% with the single parameter 'ulid' described as 'A 26-character ULID.' The description does not add new parameter details beyond what the schema already provides, so a 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 explicitly states the tool validates a ULID and extracts its creation timestamp and random component, with the additional context 'Keyless, offline.' This clearly distinguishes it from its sibling tool 'generate_ulid' and provides a specific verb-resource mapping.

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

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

The description implies usage for decoding ULIDs and notes it is keyless and offline, but does not explicitly state when to use it versus alternatives like generate_ulid or other tools. It lacks explicit when-not-to-use conditions or comparisons.

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 a write operation; description adds rate-limit (5 per identifier per day), free, no quota consumption, and that team reads daily. 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?

Well-structured: purpose first, then usage, constraints, tips. 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?

No output schema needed; description explains team reads daily and affects roadmap. Covers all necessary context for a feedback 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 100% of parameters; description adds detailed guidance on type enum and message content, and explains context fields 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 sends feedback to Pipeworx team for bugs, missing features, data gaps, or praise. Distinguishes from sibling tools which are other query/action tools.

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

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

Explicitly specifies when to use (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and free usage.

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

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

Annotations already claim readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that it's derived from CF analytics-engine, contains no PII, and is cached (5min-1h). This provides additional behavioral context beyond annotations.

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

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

The description is concise, uses bullet points for use cases, and every sentence adds value. No unnecessary information.

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

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

No output schema exists, but the description mentions the data structure (pack, tool, count). It explains caching and data source. Could mention ordering or limits, but it's sufficient for the tool's 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 the window parameter described. The description adds nuance by explaining that shorter windows surface hot trends and longer windows show steady-state demand, which goes beyond the schema's enum values.

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

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

The description clearly states it returns top tools, packs, and call volume. The verb 'Returns' and resource 'trending data' are specific. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on what other agents are calling.

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?

Three explicit use cases are listed: discovering hot data, confirming canonical tools, and aligning use cases. Guidance on window selection (shorter vs longer) is provided. No explicit when-not-to-use, but the uses are clear enough.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It details the partition check, semantic anchor with Jaccard similarity threshold, placeholder filtering, fill check with live CLOB depth, and conditions for not trading. This fully informs the user of the tool's internal logic and limitations. 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 primary purpose and modes, but it is lengthy due to detailed explanations of partition checks, similarity thresholds, and fill risk. While every sentence adds value, the overall length could be trimmed slightly for quicker comprehension. The structure is logical and well-organized.

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

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

Given the complexity of the tool (multiple modes, partition checks, fill risk, filters), the description is remarkably complete. It covers usage, parameter details, response structure (opportunities, partition_check, fill details), conditions for valid signals, and references to related tools. Despite the lack of an output schema, the description sufficiently explains 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%, but the description enriches both parameters significantly. For 'event', it clarifies acceptable formats (slugs or URLs) and mode behavior. For 'topic', it explains how the seed question is used and the cross-event scanning process. This goes well beyond the schema descriptions, providing practical usage insights.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_fill_risk by specifying unique methods and modes, such as trending_scan, event, and topic. The verb 'find' and resource 'arbitrage opportunities' are specific and actionable.

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

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

The description provides explicit guidance on when to use each mode: call with NO args for trending scan, pass event for a specific market, or topic for cross-event scanning. It recommends event mode for specific markets and explains that cross-event mode catches patterns missed by single-event scanning. Also, it directs users to polymarket_fill_risk for custom sizing, offering clear alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, and not destructive, so the description is not required to repeat these. The description adds extensive behavioral details: model families, edge calculation, Kelly sizing, 24h-move warnings, caching, and diagnostics. It fully discloses how the tool behaves without contradiction.

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

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

The description is dense but well-structured: purpose statement first, then model families, response structure, knobs, and caching. Every sentence adds meaningful information, and the structure is logical and 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 complexity (9 parameters, multiple models, nested response), the description is fully complete. It explains the by_segment structure, fed_candidates, diagnostics, and caching. No output schema exists, so the description adequately covers return values.

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%, providing detailed parameter descriptions. The description adds value by grouping knobs under 'TRADEABLE-EDGE KNOBS' and explaining the interaction between parameters like min_kelly and min_partition_leg_kelly, which goes beyond the schema.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker through its unique focus on data disagreement and edge calculation.

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 targets 'what should I bet on today' use case and provides context with filtering knobs. It mentions that Fed bets are excluded from ranking, giving implicit guidance. However, it lacks explicit when-not-to-use statements or direct comparisons with 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?

Adds significant behavioral context beyond annotations: explains snapshot triggers, gaps meaning, decay computation from daily closes, 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?

Well-structured with purpose first, then response explanation, then limits. Somewhat long but every sentence adds value. Front-loaded with the key question.

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 explains response fields (tracked, expired, snapshot_dates) despite no output schema, covering all relevant aspects and limits. Very complete for a low-complexity 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?

Description adds default values and constraints (days default 14, max 30; window default '1wk') beyond the schema. Schema coverage is 100%, so description adds useful usage context.

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

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

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge age and trend. It distinguishes from siblings like polymarket_edges by focusing on historical time-series.

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 gives clear context on when to use (e.g., comparing fresh vs old edges) and mentions limits (history depth, TTL, no intraday). However, it does not explicitly state when NOT to use or name 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and non-destructive. The description adds behavioral details: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains basket logic (thin legs, forced directional risk). No contradictions.

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

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

The description is lengthy but well-structured with sections for single-market and basket modes. Every sentence adds value, though it could be slightly more concise. It is front-loaded with the key purpose and then details modes, making it easy to scan.

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

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

Given the tool's complexity (two modes, multiple outputs, no output schema), the description completely explains return values for both modes, including fields like capture_ratio, thin_legs[], forced_directional_risk for basket, and verdict for single-market. It also covers defaults, constraints, and edge cases (e.g., partial fills).

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%, and the description adds meaning beyond the schema: explains that size_usd interpretation depends on mode (max spend vs target proceeds for single-market; settlement notional for basket), default values (1000, side auto for basket based on partition sum), and valid ranges (clamp 10–1,000,000).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, specifying inputs and outputs for each, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills create directional risk) and implies when not to use (below $500 or without those signals).

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 (readOnly, idempotent), the description reveals detailed behavioral traits: two operational modes, response structure with leg-by-leg prices and spread, safety fields like compatibility_warning, temporal_alignment, and skipped cross-type/subtype counters. It also warns about limitations of pre-mapped topics.

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 for purpose, modes, response, and safety. It is relatively long but every sentence adds value, making it informative without redundancy. Minor conciseness improvement possible.

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 thoroughly explains the return structure (leg-by-leg prices, matched spread with top_spreads_pp) and safety fields necessary to interpret results. It covers edge cases like venue mismatch and temporal alignment, providing complete context 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?

The input schema covers 3 parameters with descriptions. The description adds significant meaning by explaining how the topic parameter maps to macros, how explicit tickers override topics, and the overall mode-based behavior. It clarifies parameter interactions beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage, which focus on single-venue.

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

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

The description explains when to use each mode and warns that most pre-mapped topics return compatibility warnings, indicating limited tradability. It implicitly distinguishes from other tools by its cross-venue nature, but does not explicitly list when not to use compared to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when 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 sentences front-load the core action, then provide usage guidance, scoping, and pairing with sibling tools. Every sentence is informative, and there is no wasted text.

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 (one optional parameter, no output schema, clear annotations), the description fully covers purpose, usage, behavioral details, and context. It is complete and leaves no ambiguity.

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 schema property description already states 'Memory key to retrieve (omit to list all keys).' The tool description repeats this information without adding new parameter-specific meaning, so it adds no 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?

Clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' The verb and resource are specific, and it distinguishes from siblings like '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 tells when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also implies when not to use (when saving or deleting) and provides scoping 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?

Description indicates mark_read:true flags events as read, a mutation, contradicting readOnlyHint=true in annotations. This is a serious inconsistency.

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

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

Four concise sentences, each adding specific value. No redundancy or unnecessary text.

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 returned fields, parameter usage, and alternative access (HTTP GET). Lacks error handling details but is sufficient for a read-only 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?

Adds meaningful context beyond the schema, e.g., example type 'sec_8k', ISO timestamp for since, and behavior of mark_read.

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 and returns recent alerts with specific fields. It is distinct from sibling tools like 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?

Provides guidance on filtering by type and since, using mark_read, and notes that polling works. Does not explicitly state when not to use or 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?

Beyond annotations (readOnly, idempotent, etc.), the description discloses the multi-source fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO with soft-fail behavior. It also describes the return structure (changes grouped by source, total count, citation URIs). This adds substantial behavioral context that annotations alone do not 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 paragraph but is well-structured: it opens with usage examples, explains the multi-source behavior, covers parameter details, and closes with an alternative tool reference. Every sentence is informative, though it could be slightly more compact without losing clarity.

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

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

For a tool with no output schema and moderate complexity (multiple data sources, fallback logic), the description is remarkably complete. It specifies the input parameters, the sources queried, the fallback behavior, the return format, and points to the sibling tool for related but distinct use cases.

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

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

Schema coverage is 100% and the description adds significant value: it explains the `since` format with examples (ISO date, relative shorthand like "7d"), specifies that `value` accepts ticker or CIK, and clarifies that `type` is limited to "company". These details go beyond the schema descriptions.

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

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

The description begins with concrete query examples like "What's new with X" and states the tool provides a "change feed for a company in the last N days/weeks/months in ONE parallel call." It clearly distinguishes itself from the sibling tool entity_profile by explicitly recommending entity_profile for static profiles.

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 context for when to use this tool (queries about recent changes) and explicitly names the alternative entity_profile for static profile queries. However, it does not elaborate on when not to use it beyond that single sibling comparison.

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 idempotentHint=true and destructiveHint=false. Description adds beyond this: key-value storage, persistence for authenticated users, TTL for anonymous. No contradictions.

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

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

Four sentences front-loaded with purpose. Each sentence adds unique information. Efficient but slightly verbose; 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 simple key-value store with full schema coverage and no output schema, description fully covers usage, retention, and pairing with siblings. 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%, so baseline is 3. Description adds value by showing key naming patterns (e.g., 'subject_property') and value types (findings, addresses).

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 'Save data the agent will need to reuse later' with concrete examples (resolved ticker, target address, user preference). It distinguishes from sibling memory tools (recall, forget) by focusing on storage.

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: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Provides scope (by identifier) and retention (24 hours for anonymous). Lacks explicit when-not-to-use but context is sufficient.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable context: it cascades through several internal endpoints and returns specific fields for each type. 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 a clear purpose. While it is relatively long, every sentence adds value, explaining types and the internal cascade. It could be slightly more concise but is 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?

Despite lacking an output schema, the description fully explains return values for each type (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug). It covers the tool's complexity and use case 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?

Schema coverage is 100% with both parameters described. The description enriches the schema by providing examples, explaining auto-disambiguation for company names, and clarifying accepted values for the value 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 uses specific verbs and clearly states the tool resolves names to canonical identifiers. It gives concrete examples for each supported type and distinguishes itself from sibling tools by explaining it replaces multiple manual 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 phrase 'Use FIRST whenever you have a name but need an ID' provides explicit guidance. The description also details the two supported entity types and their inputs, though it does not explicitly state when not to use it.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe and non-modifying behavior. The description adds value by detailing the internal process (calling ai_visibility_check per entity) and output structure (ranked list with score, confidence, signal density). This contextualizes the behavior beyond what annotations alone convey. No contradiction with annotations.

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

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

The description is a concise paragraph of four sentences, each adding value: purpose, process, use case, output. It is well-structured and front-loaded with the core function. No redundant or filler sentences, though it could be slightly more terse without losing clarity.

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

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

Given the tool has one required parameter, no output schema, and annotations covering safety and idempotency, the description adequately covers what the tool does, how it works, and the nature of the output. It mentions that it ranks and returns score, confidence, signal density. While it doesn't discuss error handling or limits, the scope is sufficiently complete for an agent to understand and use the tool 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?

Input schema has 100% coverage with descriptions for all parameters. The description adds additional context: explaining that the first entity in 'entities' is treated as the 'subject' for narrative, and that omitting 'models' defaults to workers-ai. This extra meaning helps the agent use parameters correctly, justifying 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 tool's purpose: to compare AI visibility across multiple entities side-by-side. It explains the process (probes each entity with ai_visibility_check, ranks by score) and provides a concrete use case ('does Claude know about us as well as our competitors?'). This effectively distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (potentially different comparison).

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

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

The description gives a clear use case: competitive AI-marketing audits. It implies when to use this tool over alternatives (e.g., when you need multi-entity comparison vs. single-check with ai_visibility_check). However, it does not explicitly state when not to use or list alternative tools, but the context is sufficient for proper selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds significant behavioral details: composite multi-source fan-out, partial failure degradation (sources_failed list), latency note for bundlephobia first measurement (5-30s), and the structure of the returned data. 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 informative but somewhat verbose, listing return fields in detail. However, every sentence adds value, and the key information (purpose, usage, ecosystem, behavior) is front-loaded. Nearly concise, but could be trimmed slightly without losing essential context.

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

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

Given the absence of an output schema, the description thoroughly explains all returned components (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem scope, partial failure, and latency. No gaps in understanding the tool's capability.

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 both parameters. The description adds no additional detail beyond what the schema provides for parameters (package name, version optional). 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 explicitly states it is a composite check for deciding whether to add an npm package, using deps.dev and bundlephobia. It specifies the verb (scan/determine), resource (npm package dependency), and scope (license, advisories, size, tree-shaking). It clearly distinguishes from direct deps.dev calls 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?

The description directly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes the NPM-only limitation and fallback for other ecosystems, providing clear context for when to use this 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. The description adds crucial behavior: embedding model (BGE-base-en), windowing (500-char overlapping), similarity measure (cosine), character cap (200K chars with truncation flag), and return format (offsets and similarity scores). This far exceeds what annotations provide.

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

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

Three sentences: headline, use-case and benefit, technical details. Every sentence is necessary and informative. 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?

Despite no output schema, the description explains the return format (passages with offsets, similarity scores) and pairs with another tool. Covers cap, truncation, and embedding details. Fully sufficient for an agent to understand what it 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% with descriptions for all 3 parameters. Description reinforces by re-stating the text cap and adding example queries for 'query', plus default/range for 'limit'. Adds marginal value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K body, article, long tool result). It distinguishes from sibling tools by naming 'ask_pipeworx_grounded' as a complementary 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' Also provides an alternative strategy: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 minimal info (not read-only, idempotent, not destructive). The description adds critical behavioral details: account requirement, delivery constraints (SMS cap, webhook signing secret one-time return, auto-disable after 10 failures per webhook), and type-specific parameter examples. This fully compensates for the sparse 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 fairly long but highly informative, with a clear front-loaded purpose followed by organized details on types and delivery. It efficiently packs necessary information without significant redundancy, though it could be slightly more concise by merging overlapping 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?

Given the complexity (multiple types, nested delivery options, no output schema), the description covers most aspects: auth requirements, type examples, delivery constraints, and response includes subscription ID. A minor gap is lack of mention of possible error responses or subscription management, but it is largely complete for an agent to 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?

Schema coverage is 100%, but the description enriches parameter meaning by providing concrete examples for each type and additional details for delivery channels (e.g., webhook HMAC signing and auto-disable). This adds value beyond the schema definitions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and explicitly says it returns the subscription ID. This distinguishes it from sibling tools like 'list_subscriptions' (listing) and 'unsubscribe' (deleting).

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 usage context: requires a Pipeworx OAuth account, lists supported subscription types with specific examples, and explains delivery channel options and constraints. It does not explicitly state when not to use it versus alternatives, but the context is sufficient for an AI to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that it returns example questions with exact tool+argument shapes from the live catalog, providing useful behavioral context beyond annotations.

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

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

Front-loaded with alternative queries, structured as a single paragraph with clear content. Every sentence adds value, but could be slightly more concise without losing informativeness.

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 optional parameter and no output schema, the description fully explains what it does, what it returns, and when to use it. No gaps.

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

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

Schema has 100% coverage for the one parameter, so baseline is 3. The description adds value by showing examples of topic values and explaining default behavior ('omit for a cross-category spread').

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 category-bucketed example questions to help users understand what Pipeworx can do. It includes specific example queries and output structure, distinguishing it from siblings by positioning it as an onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to use the optional topic parameter, providing clear context vs 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?

The description adds significant behavioral context beyond annotations: it clarifies that the row is deactivated not deleted, ownership is enforced, and historical events remain available. This aligns with annotations (idempotent, not destructive) and provides practical implications.

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 redundancy. The first sentence states the core action, and the second provides essential constraints and effects. 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 tool's simplicity (one parameter, no output schema, with annotations), the description thoroughly covers ownership, effect on data (deactivation vs deletion), and historical availability. No gaps remain.

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 already fully describes the single required parameter 'id' as a UUID from subscribe. The description does not add additional meaning beyond the schema's description, 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 uses the specific verb 'cancel' and identifies the resource as 'subscription by id'. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing clear context for when to use. It implicitly suggests using this tool instead of deletion when history retention is desired, though it does not explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond annotations: it explains the two internal routing paths (SEC EDGAR vs. grounded pipeline), the return fields (verdict, actual value with citation, reasoning), and the behavior for different claim types. It does not contradict annotations. Missing details like rate limits or failure modes, but given the rich annotations, the description adds good value.

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 purpose and usage examples. It is informative but slightly lengthy; every sentence adds value. It could be more structured (e.g., bullet points for return fields) to improve scanability, but it is not overly verbose. The conciseness is adequate given the amount of 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 tool's complexity (two routing paths, two parameters) and the lack of an output schema, the description is fully complete. It explains the return values (verdict, actual value with citation, reasoning) and how the tool works internally. The rich annotations further support understanding. An agent can confidently use this tool based on the description alone.

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%, yet the description adds significant meaning beyond the schema. For 'claim', it provides natural-language examples and clarifies it's a factual claim. For 'tolerance_pct', it explains that it overrides the implied tolerance, gives usage guidance (set 1–2 for hallucination detection), and notes the default. This enriches the agent's understanding of how to use the parameters effectively.

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

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

The description clearly defines the tool's purpose: natural-language claim verification against authoritative sources. It provides multiple verb examples ('fact check', 'verify', 'confirm/refute') and specifies the resource (claim verification). It distinguishes between company-financial claims (via SEC EDGAR) and other claims (via grounded pipeline), setting it apart from siblings.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and explains the two routing paths for different claim types. It implies that for financial claims, the structured path is faster, and for others, the grounded pipeline routes to the right source. However, it does not explicitly state when NOT to use it (e.g., subjective opinions or non-factual queries), 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.