Commons Wikimedia

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, consistent with a probing tool. The description adds behavioral context: it mentions default model, note about Anthropic API key being passed directly (BYO key), and the return structure. No contradictions.

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

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

The description is a single paragraph of about 4 sentences, efficiently conveying purpose, defaults, options, and return format. It is front-loaded with the core action and score range, followed by details and use cases. No wasted words.

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

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

Given no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response, combined view). All 4 parameters are described and contextualized. The complexity of multiple models and optional API key is fully addressed. The tool seems adequately described for an agent.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds valuable context: clarifies 'entity' as the thing to ask about, 'models' default to workers-ai, '_apiKey' is passed through directly to Anthropic, and 'context' helps disambiguate. This goes beyond the schema's bare descriptions.

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

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

The description specifies the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score (0-100) per model. It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on LLM visibility rather than general scanning, and from 'ask_pipeworx' variants by providing a structured score.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also specifies when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use this tool or suggest alternative sibling tools for different scenarios.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond that: it routes across 5,798 tools and 1,517 verified sources, fills arguments automatically, returns stable pipeworx:// citation URIs, and handles live-news routing. It does not deeply discuss failure modes or answer formatting, but the annotation coverage lowers the burden.

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

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

The description is longer than average but earns its length by front-loading the key 'prefer over web search' instruction, providing concrete examples, and clearly separating the default tool from alternatives. The later section is somewhat run-on and could be tightened, but the structure is still effective and scannable.

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?

Although there is no output schema, the description states that the tool returns a structured answer with stable citation URIs, which is the key expectation for an agent. It covers when to use it, what kind of questions to send, what data domains are included, and when to route to specific sibling tools. This is sufficient for a tool with this complexity.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the single natural-language 'question' parameter. The description reinforces the intended usage with concrete example questions, but it does not add substantial semantic detail beyond what the input schema already 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 that ask_pipeworx routes natural-language questions to the appropriate tool among thousands and returns a structured, cited answer. It distinguishes this tool from siblings like ask_pipeworx_grounded and deep_research by describing its role as the default option rather than the grounded or multi-source fan-out alternative.

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 explicit guidance: prefer over web search for factual/real-world questions, use whenever the user asks common lookup phrasings, and start here for most questions. It also names exact alternatives and conditions for stepping up to ask_pipeworx_grounded or deep_research, plus note that breaking-news questions are already handled internally.

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

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

The description discloses that no candidate is active as of 2026-07-26, that behavior currently matches the stable router, and that it falls back to nothing—a full working router rather than a stub. It adds meaningful context beyond the annotations (readOnly, openWorld, idempotent). Minor gap: does not disclose rate limits or potential instability of an experimental edge, but the core behavior is clearly disclosed.

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

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

The description is information-dense and front-loaded with the key routing distinction, followed by current-state context and a clarifying caveat. It earns its length, though the parenthetical about candidate retirement adds more detail than strictly necessary.

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 a single required string parameter, full schema coverage, rich annotations, and no output schema, the description sufficiently explains what the tool does, how to use it, and how it differs from the stable sibling. It does not explain return values, but the stable sibling's shared response shape is referenced and the schema is simple enough that this is a minor gap.

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 all six parameters are aliases of the single required 'question' parameter, with complete schema descriptions. The description adds that it accepts 'same arguments' as ask_pipeworx, but does not need to add more because the schema already fully documents the parameters.

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

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

The description explicitly identifies this as the beta version of ask_pipeworx, states it is a universal router with the same tools/arguments/response shape, and clarifies its current state relative to the stable version. It distinguishes itself clearly from the sibling ask_pipeworx and other 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?

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains results are compared against the stable router. It also clarifies that it currently matches ask_pipeworx exactly, which prevents an agent from expecting differences.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses the full behavioral contract: the success return shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, the complete enumeration of refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the explicit-refusal behavior when data doesn't directly answer, and the extra LLM call cost. 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 long (~120 words) but every sentence earns its place: purpose, mechanics, success return shape, refusal contract, when-to-use, and cost tradeoff — all in a logical flow. It is front-loaded with the most decision-relevant information. The length is justified because there is no output schema, so the return and refusal shapes must be carried in prose.

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 fully compensates by documenting both the success response and the refusal response with all enum values. It covers routing behavior, the distinction from ask_pipeworx, the usage conditions, and the cost tradeoff. Nothing an agent needs to invoke it correctly or parse its response 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 baseline is 3 per the rubric. The schema already documents the question parameter with all six aliases (query, q, prompt, text, input) and says 'Your question in natural language.' The description adds only indirect context ('fills arguments') and doesn't provide parameter syntax or format details beyond what the schema covers. At baseline, this is acceptable.

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

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

The description opens with a specific verb-resource pairing: 'Hallucination-resistant answer mode for high-stakes reads' — a grounded question-answering mode. It clearly differentiates from the sibling ask_pipeworx by naming the 'Same routing' shared mechanic and the key differentiator: extracting the answer using ONLY what the tool result contains. An agent can distinguish this from ask_pipeworx, ask_pipeworx_beta, and bet_research without opening schemas.

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

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

Explicit when-to-use is stated: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative directly and gives the exclusion condition: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is textbook routing guidance.

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

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

The description extensively covers behavioral details beyond annotations: fan-out patterns, response shapes, resolution logic, safety checks (low-confidence, closed markets, wide spreads), and cancellation rules. Annotations already declare readOnlyHint, but the description adds crucial context for safe usage 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 very long and dense, covering many edge cases and technical details. While well-structured with labeled sections, it could be more concise. Every sentence adds value, but the length may overwhelm agents; a slightly tighter summarization would improve.

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

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

Given the tool's complexity (multiple classifiers, fan-out examples, response shapes, edge cases), the description is extremely complete. It covers failure modes, low-confidence matches, closed markets, wide spreads, and cancellation rules. No output schema exists, but the description explains response fields thoroughly.

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

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

Schema coverage is 100%, baseline 3. The description adds significant meaning: explains that 'market' can be slug, URL, or text; 'depth' defaults to 'thorough'; 'include_raw' default false with guidance on when to set true. Examples in schema further clarify. Goes beyond 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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and differentiates from sibling tools like polymarket_edges by emphasizing comprehensive research for a single bet.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies when to use the tool but does not explicitly state when not to use it or compare to alternatives. Clear enough for an agent to decide.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds no behavioral context. It fails to mention pagination (cmcontinue), rate limits, or output structure, missing an opportunity to enhance transparency.

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 under-specified to the point of being unhelpful. While short, it fails to convey essential information, making it ineffective rather than concise.

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

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

With 3 parameters and an output schema, the description should clarify what the tool returns and how pagination works. It does not, leaving significant gaps for an AI agent to infer correct usage.

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

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

Schema coverage is 33% (only category has a description). The description does not explain the purpose of limit, cmcontinue, or how they interact. It adds no value beyond the schema's minimal documentation.

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

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

The description 'Items in a Commons category.' is a noun phrase and does not specify the action (e.g., list, retrieve). It vaguely hints at the resource but lacks a clear verb, making it insufficient for an agent to understand what the tool does.

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?

No guidance is provided on when to use this tool versus alternatives. Sibling tools like search or entity_profile could overlap, but the description does not differentiate or suggest appropriate contexts.

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 discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), metrics (revenue, net income, etc.), handling of off-calendar fiscal years, and output format (paired data + citations). Annotations already indicate read-only, open-world, idempotent behavior; description adds rich 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?

Description is 4–5 sentences with front-loaded examples and key instructions. Every sentence adds value, though it could be slightly more structured. 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?

Covers all relevant aspects for a tool with no output schema: data sources, metrics, sorting, output format, and efficiency gain (replaces 8–15 lookups). Complete for its complexity.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds value by explaining that type='company' pulls SEC data and type='drug' pulls FAERS/FDA/trial data, and gives example values. Baseline 3, elevated to 4 due to added 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 performs side-by-side comparisons of 2–5 companies or drugs, with specific verb phrases like 'compare X and Y', 'which is bigger', 'rank these companies'. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

Explicitly advises to ALWAYS PREFER this tool over sequential single-pack lookups for comparisons. Provides examples of when to use (e.g., 'which is bigger', 'head to head') and constraints (2–5 entities). No when-not-to-use is needed given the specificity.

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

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

Annotations already provide readOnly and idempotent hints, but the description adds substantial behavioral detail beyond them: account requirements, parallel decomposition into facets, findings packet structure with citations and gaps array, never-invented policy, contradiction scanning, semantic excerpting, and latency expectations. This goes far beyond what annotations alone 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 long but information-dense, and nearly every sentence carries critical operational detail. It is front-loaded with the account requirement and the alternative tool, then flows logically into behavior, depth tiers, output structure, and timing. Some density could be reduced, but for a tool this complex the length is justified.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It covers input semantics, behavioral variability by depth, timing, auth requirements, and relation to alternatives. 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 baseline is 3. The description adds useful semantics for the depth parameter by explaining what quick/standard/thorough actually do (facets, hops, gap recovery, lead chasing) and that thorough is paid. It also clarifies that question accepts natural-language broad/multi-part questions, adding context 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 identifies a specific verb and resource: 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, explicitly distinguishing it from open-web search. It also contrasts itself with ask_pipeworx, making it easy to tell 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 gives explicit usage conditions: use it for broad/multi-part questions over structured data, use ask_pipeworx instead for single lookups, and use ask_pipeworx when not signed in. It also mentions depth tiers and paid requirements, providing clear routing guidance.

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

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

Annotations already mark as read-only and idempotent. Description adds value by explaining return format (full schemas, curated examples) and that results are ready to call.

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

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

Description is moderately concise, front-loads purpose, and avoids fluff. Could be trimmed slightly but overall efficient.

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

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

Despite no output schema, description explains what is returned (names, descriptions, schemas, examples). Covers behavioral aspects and usage context well 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% with descriptions for all 6 parameters. Description mentions aliases and gives examples but does not add significant meaning beyond schema.

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

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

Clearly states 'Find tools by describing the data or task' with specific verb and resource. Distinguishes itself from sibling tools like 'search' by focusing on tool discovery.

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' and lists domains like SEC filings, FDA drugs, etc. Gives clear use case scenarios, though lacks explicit 'when not to use'.

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

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

Even though annotations already declare readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral context: it fans out across many sources, explains sources_used/sources_failed semantics, reports the USPTO API sunset and soft-fail, says empty FDA sections are expected rather than bugs, and describes the private-company resolved:false path. There is 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 long but dense and well-organized, front-loading examples and the core purpose before enumerating sources, outputs, and failure semantics. Given the complexity of a multi-source profile with no output schema, the length is mostly earned, though a few details repeat what the parameter schema already states.

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?

There is no output schema, so the description correctly carries the full burden of explaining return shape. It enumerates every returned section, describes per-source behavior and fallbacks, explains what empty sections mean, and covers input resolution outcomes including private-company handling. Nothing essential for correct invocation and interpretation 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 coverage is 100% and the schema descriptions already explain the type enum and value formats, so the baseline is 3. The description adds meaning beyond that by clarifying that company and ticker are interchangeable, giving examples, explaining zero-padded CIK handling, and documenting private-company resolution behavior with resolved:false and notes. This is meaningful but incremental.

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

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

The description opens with concrete trigger phrases ('Tell me about X', 'research Acme', 'company profile for Microsoft') and then states the specific verb+resource: full cross-source profile of a US public company in one parallel call. It also explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, so an agent can separate it from sibling lookup 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?

It says explicitly to prefer this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, and it gives exclusion conditions such as person/place not yet supported and private companies returning resolved:false. However, it does not name specific sibling alternatives like compare_entities or deep_research, so the routing is clear but not fully mapped to the sibling list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is well-covered. The description adds no new behavioral details (e.g., error cases, rate limits, or data freshness). Adequate but not enhanced.

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 sentence listing key metadata fields, with no extraneous content. Efficient and front-loaded. Could be slightly more structured (e.g., bullet points), but within acceptable limits.

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 (1 simple parameter, rich annotations, and an output schema present), the description covers the core purpose and return fields. Lacks usage guidance, but overall adequate for a read-only lookup 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%, so the parameter 'title' is fully documented in the schema. The description does not add extra meaning beyond listing return fields, which is not about the parameter. Baseline 3 is appropriate as the description provides no additional semantic value for parameters.

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

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

Description specifies the resource ('File metadata') and lists specific fields (size, mime, license, upload date, thumbnail urls), clearly indicating what is returned. It distinguishes from sibling 'file_revisions' by focusing on current metadata rather than version history. Missing an explicit verb like 'retrieve' or 'get', but still strong.

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?

No guidance on when to use this tool versus alternatives like 'file_revisions' or search tools. The description does not mention prerequisites, limitations, or context for usage, leaving the agent to infer without clear direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the name itself, such as authorization requirements or rate limits.

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

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

While short, the description is under-specified and does not front-load essential information. Single phrase lacks structure; every word does not earn its place because it fails to add value.

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

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

Given the low schema coverage and missing parameter documentation, the description is incomplete. Even though an output schema exists, the input side is not adequately described for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description does not explain the purpose or constraints of the 'title' or 'limit' parameters. The agent has no guidance on how to use them.

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 'File revision history.' is essentially a tautology, restating the name 'file_revisions' and title 'File Revisions'. It does not use a specific verb or resource to differentiate from siblings like file_info.

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?

No guidance is provided on when to use this tool versus alternatives (e.g., file_info). The context signals show many sibling tools, but the description offers no context.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description adds 'delete' which is consistent with the annotation. No extra behavioral context beyond what annotations indicate. Adequate but not additional 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?

Two sentences, front-loaded with action and resource. Every sentence is useful, no 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?

Simple tool with one required parameter and no output schema. Description covers purpose, usage, and parameter. Could mention return behavior (e.g., success confirmation) but not essential.

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

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

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so description adds no new meaning. 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?

Description clearly states 'Delete a previously stored memory by key.' Verb+resource is specific, and it distinguishes from sibling tools like '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 says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall. Could be improved by noting when not to use, but guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by stating the tool fetches the page, extracts title/description/key links, and emits standard markdown. This provides a clear process 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 three sentences long, front-loads the main purpose, and lists use cases concisely. No fluff or unnecessary details, though it could be more structured with bullet points for readability.

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

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

Given the tool's simplicity (2 parameters, no output schema, rich annotations), the description covers core behavior and use cases. It lacks details on error handling or edge cases (e.g., invalid URL), but for a straightforward read-only tool, it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add new meaning about parameter syntax or constraints 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 a production-ready llms.txt file for any URL, specifying the output format and purpose for AI crawlers. It distinguishes itself from sibling tools by focusing on generating a specific file for AI indexing.

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

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

The description lists concrete use cases: indexing client sites, drafting personal llms.txt, and auditing competitors. It does not explicitly mention when not to use the tool or provide alternatives, but the context is clear enough for an agent to decide appropriately.

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 return fields and usage context, but doesn't disclose additional behavioral traits like pagination or rate limits. No contradiction with annotations.

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

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

Two sentences: first states what it does and returns, second gives usage guidance. No fluff, information is front-loaded.

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

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

For a simple read tool with one optional parameter and rich annotations, the description fully covers purpose, return values, and usage scenarios. No output schema needed.

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

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

Schema coverage is 100% with description for 'include_inactive'. The tool description reinforces that it lists active subscriptions by default, adding meaning beyond the schema.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools like subscribe and unsubscribe by focusing on read-only listing.

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 to review what you're monitoring before adding more or to find an id to cancel', providing clear context and alternatives (subscribe/unsubscribe).

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 set readOnlyHint=false and destructiveHint=false, but the description adds meaningful context beyond this: rate limits ('5 per identifier per day'), no tool-call quota impact, claim_token behavior, and daily digest review. 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?

While longer than average, every sentence earns its place: purpose, exclusions, content rules, token flow, and operational details. It is front-loaded with the main action and structured logically 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?

The description covers the full feedback lifecycle: when to use, what to include, how to check resolution, scope boundaries, and rate limits. Given the nested context object and two-mode usage, it provides complete guidance even without an output schema.

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

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

Schema covers all 4 parameters (100%), but the description adds cross-parameter value by illustrating the two workflows: filing with message/context and later reading via claim_token, including a concrete invocation example. It also clarifies that context should reference Pipeworx tools/packs, enriching the semantics.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the types of feedback (bug, feature/data_gap, praise), making it distinct from sibling research/data tools.

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

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

The description gives explicit when-to-use conditions (tool returns wrong data, tool you wish existed, praise) and when-not-to-use (for tools from other MCP servers), even directing users to file elsewhere. It also provides content guidance: describe in terms of Pipeworx tools, don't paste the end-user prompt.

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, destructiveHint. Description adds: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides extra 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?

Four sentences, no wasted words. Front-loaded with the core output, followed by use cases and supplementary details. Each sentence adds value.

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

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

No output schema, but the description clearly states what is returned (top tools, top packs, total call volume). Combined with thorough annotations, the description is complete for a simple trending 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% and already describes the window parameter with enum and description. The description adds value by explaining the effect of window length on the results, which is not in the schema.

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

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

The description explicitly states what the tool returns: 'top tools, top packs, and total call volume over a recent window.' The verb 'returns' and resource 'trending data' are clear. It is distinct from siblings like 'ask_pipeworx' or 'search' which are query-based.

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 three specific use cases and gives guidance on window selection: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Implicitly tells when not to use (when PII or detailed call data is needed).

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, and destructiveHint. The description adds substantial behavioral context: monotonicity checks, partition-sum logic, semantic anchor, partition filter, fill check with CLOB depth, and response structure. This goes well beyond annotations and is internally consistent.

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

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

The description is detailed and well-structured, front-loading the purpose and modes. However, it is somewhat lengthy with technical jargon (e.g., 'Jaccard similarity', 'partition_sum_yes_prices'), which could be condensed 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?

Despite no output schema, the description fully explains the response structure (opportunities array with fields, partition_check object). It covers edge cases (skipped_low_similarity, placeholder filter, fill check) and references a related tool (polymarket_fill_risk). The description is complete for a complex tool with multiple modes.

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

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

Schema description coverage is 100% with descriptions for both parameters. The tool description adds significant value: explains mode semantics, provides concrete examples (event slugs, seed questions), and specifies URL acceptance. This far exceeds the baseline of 3 for high coverage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (default, event, topic) with specific use cases, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description gives explicit when-to-use instructions for each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It recommends event mode for specific markets. However, it does not provide comparisons to sibling tools or explicit when-not-to-use scenarios.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral details: model families, edge metrics, response segments, tradeable-edge knobs, and diagnostics, far exceeding the annotation baseline.

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

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

The description is front-loaded with the core purpose and well-structured with sections for models, knobs, and response format. However, it is quite verbose, containing detailed explanations that could be condensed.

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

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

For a complex tool with 9 parameters, no output schema, and intricate internal logic, the description is remarkably complete. It covers response structure (by_segment), edge metrics, filtering knobs, caching behavior, and diagnostics for empty segments, leaving no significant gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds some extra context about knob usage (e.g., 'min_liquidity drops opportunities where edge isn't realizable'), but this is marginal given the schema already explains each parameter well.

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

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

The description clearly states the tool scans Polymarket markets for discrepancies with Pipeworx data, specifying it's for 'what should I bet on today' agents. However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Provides clear context for when to use the tool (discovering betting opportunities without paging hundreds of markets) but lacks explicit when-not-to-use guidance or mention of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant transparency: data source (daily snapshots), decay calculation details, limitations (60-day TTL, snapshot gaps), and response structure (tracked, expired, snapshot_dates). 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 fairly long but well-organized: purpose, args, response shape, limitations. It is front-loaded with the core question. Could be slightly more concise by integrating limitations into response description, but all information is valuable.

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

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

Given no output schema, the description thoroughly explains the three response arrays (tracked, expired, snapshot_dates) with field meanings. It also covers limits (60-day TTL, snapshot gaps) and data interpretation (decay based on daily closes). Complete for a telemetry 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 context: default values, clamps, and window families with examples. It explains the meaning of 'days' (lookback) and 'window' (snapshot family) beyond schema descriptions.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' answering specific questions about edge duration and decay. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current snapshots.

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

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

The description explains when to use the tool (to assess edge age and decay) and contrasts new vs stale edges. It implicitly distinguishes from polymarket_edges but does not explicitly list alternatives or when not to use, which would make it a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it walks the ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is detailed and front-loaded with the main purpose and required parameters. It is longer but every sentence adds value. Could benefit from slightly more structured formatting (e.g., bullet points for return fields), but remains clear and efficient.

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

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

Despite no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also addresses critical context about partial basket fills and directional risk, making it complete for a check 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 adds significant meaning: explains default behavior for size_usd (max spend on buys, target proceeds on sells), side defaults (auto for basket), and basket size_usd as settlement notional. Goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific verbs and resources. It is highly specific and differentiates from 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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills convert arb to directional). Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare the tool read-only, idempotent, open-world, and non-destructive, and the description adds far more: pairing_unverified is set whenever pairs are returned, temporal_alignment null means not computed rather than aligned, fees are gross and not modeled, and returned compatibility codes can be non-empty even when matched_pairs>0. This is exemplary disclosure of behavioral quirks beyond the structured hints.

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

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

The description is long, but the tool's no-output-schema status and complex safety-codes semantics justify the length. It front-loads the purpose and uses all-caps labels like TWO MODES, RESPONSE, and SAFETY FIELDS to aid scanning, though a few points (notably temporal_alignment_unknown) are explained twice and could be tightened.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does: leg-by-leg prices, top_spreads_pp sign, skipped_unclassified, low_confidence_pairs, compatibility_codes semantics, fees_note, and skipped_cross_type/subtype counters. It also sets realistic expectations about pre-mapped topics, leaving no material gap for an agent deciding whether and how to call the tool.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics beyond that: `topic` is a pre-mapped macro shortcut, the explicit parameters override the topic-mapped sides, and both modes run the 'identical token-overlap matcher' with the same disclosures. That pushes it above baseline, though the schema was already strong.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which makes the core function unmistakable. It also clarifies the two modes and the sign convention (Kalshi − Polymarket), but it never explicitly distinguishes this tool from sibling tools like polymarket_arbitrage or polymarket_edges, so it falls just short of full differentiation.

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

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

The description gives clear operational guidance: when to use `topic` shortcuts versus explicit `kalshi_event_ticker`/`polymarket_event_slug` pairings, and warns that most pre-mapped topics currently return compatibility_warning. It does not, however, state when to prefer this over sibling spread/edge tools, so there is solid context but no explicit exclusions or alternative-selection rules.

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 claims 'random image' which suggests non-deterministic behavior, but the annotation idempotentHint=true contradicts this by implying the same input yields the same output. This contradiction undermines clarity.

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 sentence that conveys the essential purpose without extraneous words. It is appropriately front-loaded and concise.

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

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

Given the tool's simplicity and the presence of annotations and output schema, the description covers basic functionality. However, the contradiction with idempotentHint and lack of details about return format (though output schema exists) leave room for improvement.

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

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

The description adds that the category parameter is optional and filters the image, which is not present in the schema (0% coverage). However, it does not specify valid category formats or provide examples beyond what appears in the schema's examples array.

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 retrieves a random image, optionally filtered by category. It distinguishes itself from sibling tools which are unrelated to images.

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?

No guidance on when to use this tool versus alternatives. The description implies its purpose but does not specify any conditions, exclusions, or related tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and is a retrieval operation. It also mentions pairing with 'remember' for saving and 'forget' for deletion, enhancing transparency beyond the annotations.

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

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

The description is concise (three sentences) with no redundant words. It front-loads the main action, provides examples, and pairs with related tools efficiently. Every sentence adds value, making it highly effective.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is complete. It explains the purpose, usage pattern, scoping, and relationship with sibling tools. No gaps remain for an AI agent to fill.

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

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

With 100% schema coverage and only one optional parameter, the description adds significant meaning: it explains that omitting the key lists all saved keys, and provides concrete examples ('user_research_topic' and empty object). This fully compensates for the minimal schema, exceeding 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 identifies the verb 'Retrieve' and the resource 'a value previously saved via remember', with the alternative of listing all keys if the key argument is omitted. It distinguishes from sibling tools like 'remember' and 'forget' by explicitly pairing with them, making the purpose specific and unambiguous.

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

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

The description provides clear context for when to use the tool (look up stored context like ticker, address, notes) and explicitly states the behavior when the key is omitted (list all keys). It does not include explicit when-not or alternatives, but the pairing with 'remember' and 'forget' implies appropriate usage boundaries, earning a 4 instead of 5.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds specific behavioral details: returns source, citation_uri, raw payload; mark_read flag changes subsequent calls; polling works. No contradiction.

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

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

Concise, front-loaded with main action, every sentence adds value. 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?

No output schema, but description mentions return fields. Covers usage, filtering, read flag, polling. For a read tool, it is fairly complete, though more detail on pagination or performance could be added.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaningful context for type, since, and mark_read parameters, explaining their effect and examples, which goes beyond 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?

Uses specific verb 'Pull fired events from your subscription feed', clearly distinguishes from sibling tools like list_subscriptions, subscribe, unsubscribe. Mentions return fields and filtering.

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 states when to use: to get alerts, with filtering options. Mentions polling and alternative access via URL. Does not explicitly say when not to use 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 declare readOnlyHint and idempotentHint. The description adds valuable behavioral info: fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and response structure. No contradictions.

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

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

The description is informative but slightly lengthy. It front-loads with example queries and efficiently packs source details, fallback logic, and parameter guidance. Nearly every sentence adds value.

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

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

Despite no output schema, the description adequately specifies return structure (changes grouped by source, total_changes count, citation URIs) and covers edge cases (USPTO soft-fail, API sunset). Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description enriches with examples (e.g., relative shorthand '7d', '30d', '3m', '1y') and usage advice ('Use "30d" or "1m" for typical monitoring'), adding meaning beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using specific verbs like 'What's new' and 'latest on'. It distinguishes from the sibling tool entity_profile, which serves 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?

Explicit examples and contexts are provided (e.g., 'What's new with X'), and it advises using entity_profile for static profile needs. However, it does not explicitly contrast with other search or monitoring tools among siblings, leaving some ambiguity.

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

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

Annotations declare idempotentHint=true and destructiveHint=false. Description adds key behavioral details: key-value pair scoped by identifier, persistence difference between auth and anonymous (24hr), and mentions storage lifetime. 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, each adding essential information. Front-loaded with purpose, then usage, then behavioral detail. 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 tool's simplicity (2 params, no output schema), the description fully covers usage, behavior, lifetime, and pairing with sibling tools. No gaps for an agent to misuse.

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. Description adds value with naming conventions and example keys like 'subject_property', 'target_ticker', and explains value as 'any text'. Provides useful context beyond schema.

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

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

Clearly states 'Save data the agent will need to reuse later', with specific verb 'save' and resource 'data'. Distinguishes from sibling tools 'recall' and 'forget' mentioned directly. Highly specific.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward' with concrete examples. Mentions pairing with recall/forget. Could be improved by noting when not to use (e.g., large data), but overall strong.

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

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

Annotations already declare read-only, open-world, and idempotent behavior, and the description adds substantial context: it lists the underlying sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), discloses that unresolved identifiers are returned under 'unresolved', and explains graceful degradation when enrichment services are unavailable. It also reveals ambiguity handling via 'figi_candidates' and that non-equity instruments resolve here.

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 intent examples and the 'Use FIRST' directive, which is good. However, the company-type section is a single extremely long run-on paragraph with nested parentheticals and a lot of detail, making it harder to scan. The content is valuable, but the structure could be tightened.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: it names the returned identifiers per entity type, documents source labels, the 'unresolved' field, 'figi_candidates' for ambiguous matches, and enrichment degradation. It also covers accepted input forms per type, making the tool's behavior sufficiently complete for an agent.

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

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

The schema has 100% coverage, so the baseline is 3, but the description adds critical semantics beyond the schema. It clarifies that 'value' accepts ticker, CIK, ISIN, or company name for 'company', and warns to pass only the entity name, not the full noun phrase, because trailing security-class words will fail the FIGI lookup. This materially improves correct argument construction.

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

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

The description opens with concrete user intents and states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' The verb 'resolve' and the clear resource (names to identifiers) distinguish it from sibling tools like search or entity_profile. The directive 'Use FIRST whenever you have a name but need an ID' further sharpens its role.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and notes that it replaces 2-3 manual lookups by cascading through several endpoints. It does not explicitly name alternative tools or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Description adds valuable behavioral context beyond annotations: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns ranked list with score, confidence, signal density. 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?

Two sentences with an example, front-loaded purpose. Each sentence contributes. Could be slightly more concise 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?

Given 4 parameters, no output schema, and rich annotations, the description covers purpose, usage, parameter behavior, and output sufficiently for an agent to understand 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%, baseline 3. Description adds meaning: explains that first entity is treated as 'subject' for narrative, others as competitors, clarifies models parameter options and _apiKey purpose, and provides context parameter use.

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 compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI visibility'. It distinguishes from sibling ai_visibility_check by emphasizing multiple entities and ranking.

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

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

Provides explicit usage context: 'useful for competitive AI-marketing audits' with an example question. Does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with purpose. Each sentence adds value, though it is somewhat lengthy. It efficiently covers purpose, usage, return details, limitations, and error handling.

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 (composite from two sources, many return fields, error handling), the description covers all essential aspects: purpose, usage, return structure, limitations, and graceful degradation. No output schema, but return fields are detailed sufficiently.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds minor context like NPM-only and version defaults, but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool is a composite check for adding an npm package to a project, combining data from deps.dev and bundlephobia. It distinguishes itself from siblings by focusing on npm packages and a specific use case.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only scope and redirects other ecosystems to deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'full-text search' but no further behavioral traits such as rate limits or result details.

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 clear sentence front-loaded with the action. It is concise but lacks informative depth necessary for effective tool selection.

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 4 parameters, an output schema, and many sibling tools, the description is insufficient. It omits pagination behavior, namespace usage, result format, and differentiation from similar search tools.

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 50% (descriptions for limit and namespace only). The description does not add meaning for query or offset parameters, failing to compensate for the low coverage.

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

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

The description clearly states the verb 'search' and the resource 'Commons', indicating full-text search. However, it does not distinguish from sibling tools like 'search_within' or 'deep_research', which have overlapping purposes.

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?

No guidance on when to use this tool versus alternatives such as 'search_within' or 'category_members'. The description provides no context for appropriate usage scenarios.

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

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

Provides rich detail beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars, truncated and flagged). No annotation 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 somewhat lengthy but well-structured with a clear first sentence, examples, and technical details. Every sentence contributes value; no redundancy. Front-loaded with key information.

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

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

For a tool with 3 parameters, no output schema, its description explains return format (passages with offsets and scores), technical details (embedding model, cap), and usage context. It is complete enough for an agent to select and invoke correctly.

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

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

Schema descriptions already cover all three parameters (text, limit, query) with good detail. The tool description adds context on usage (e.g., 'pass the text you already pulled') and explains the return format, adding meaning beyond the schema for agent understanding.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article) and specifics about output (passages, offsets, similarity scores). It distinguishes from siblings by emphasizing it searches within already-fetched text, contrasting with broader search 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 'use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages). Mentions pairing with ask_pipeworx_grounded. Lacks explicit guidance on when not to use, but the positive guidance is strong.

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

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

Annotations already provide idempotentHint=true, openWorldHint=true. The description adds context about account requirements, delivery channels, and rate limits (10/day for SMS). However, it does not clarify idempotency; the phrase 'Returns the new subscription id' might imply non-idempotent behavior, potentially contradicting the idempotentHint annotation. Overall, useful but with a minor 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?

The description is relatively long but all information is relevant and efficiently presented. It front-loads the core purpose and then lists types and delivery options in a structured manner. A slightly more uniform formatting could improve readability, but it 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 complexity (3 parameters, nested objects, no output schema), the description fully covers input semantics, including all subscription types, parameter structures, delivery channels with constraints, and account requirements. It also mentions the return value. No obvious 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%, but the description adds substantial meaning beyond schema definitions. For each type, it provides concrete examples (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE") and explains requirements. The delivery object is elaborated with phone verification, webhook signing, and auto-disable conditions.

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

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

The description clearly states the verb 'Create a proactive monitoring subscription' and the resource 'live-data event stream'. It also specifies the return value 'Returns the new subscription id'. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit guidance on when to use: creating subscriptions for live data events. It lists supported types with examples and delivery options. It also states a prerequisite: Requires a Pipeworx OAuth account. However, it does not explicitly mention when not to use or contrast with alternatives beyond implicit differentiation.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already convey safety and idempotency. The description adds detail about the response format (category-bucketed example questions with tool+argument shapes) and the optional topic parameter, which provides useful 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 well-structured, starting with common queries, then explaining response characteristics, and ending with usage guidance. It is informative but slightly verbose; however, all sentences add value.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool and argument shapes) and the effect of the topic parameter. For a tool with a single optional parameter, this provides complete context for the 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 coverage is 100%, but the description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter (full spread). This provides guidance the schema alone does not.

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 category-bucketed example questions and serves as the onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it's for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. Provides clear usage context, and the description implies when not to use it (if already familiar).

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

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

Description adds ownership enforcement and deactivation (not deletion) behavior beyond annotations. Annotations already indicate non-destructive, but the description provides important context that it's a soft cancellation.

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, front-loaded with core action, no filler. Every sentence adds value.

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

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

For a one-parameter tool with clear annotations and no output schema, the description fully covers purpose, ownership constraints, and side effects.

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 adequate description for the single parameter. Description does not add extra detail beyond what schema provides, so baseline score of 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?

Description clearly states the action ('Cancel a subscription by id'), specifies the resource ('subscription'), and distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Mentions ownership enforcement ('only cancel your own subscriptions'), guiding when to use. Implies when not to use (others' subscriptions) and explains non-destructive behavior 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?

Annotations already state readOnlyHint=true, destructiveHint=false, but the description adds significant behavioral context: routing logic, the distinction between could_not_verify (check did not happen) and unsupported (no source covers it), and the explicit warning that could_not_verify must not be treated as evidence. These details go well beyond the annotations and help the agent interpret results safely.

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

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

The description is long but well-structured: triggers, usage, routing, return values, special verdicts, and efficiency. Each sentence contributes substantive information, though some redundancy exists (e.g., repeating the 'could_not_verify' warning). It is appropriately verbose for the tool's complexity, but not maximally concise.

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

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

With no output schema, the description compensates by enumerating the verdict types and explaining the two ambiguous ones (could_not_verify, unsupported). It covers input expectations, routing, evidence citation, and why this tool is a shortcut over multiple calls. Given the tool's complexity, this is a complete picture for an agent to select and invoke it.

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

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

Although schema coverage is 100%, the description adds crucial semantics: for tolerance_pct it explains how it overrides the claim's implied tolerance, recommends 1–2 for hallucination detection, and states the default is capped at 5. For claim, it provides realistic examples. This enriches the schema descriptions and guides correct 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 verifies natural-language factual claims ('fact check', 'verify the claim that…') against authoritative sources. It distinguishes from siblings by detailing the structured SEC EDGAR fast path for company-financial claims and the grounded pipeline for all other claims, and notes it replaces 4–6 sequential calls, making its unique role explicit.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives concrete criteria for when to use the fast path vs grounded pipeline. It also clarifies the meaning of could_not_verify and unsupported verdicts, guiding callers on how to interpret results, which effectively says when the tool's answer is not usable.

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