Lyrics Ovh

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

Adds beyond annotations: default model (free Workers AI), BYO key for Anthropic, return structure (per-model score/confidence/signals/raw_response + combined view). No contradiction with annotations (readOnly, openWorld, idempotent).

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

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

Two sentences front-loaded with main action and result. Every clause adds unique information: free default, BYO key, return fields, use cases. No redundant 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 covers key output fields (score, confidence, signals, raw_response) and combined view. Mentions disambiguation context parameter. Slightly vague on 'signals' but sufficient for agent understanding.

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

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

Schema coverage 100% and description adds value: explains default model, score range 0-100, context disambiguation, and that _apiKey is passed directly to Anthropic. Significantly enriches schema definitions.

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

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

Description uses specific verb 'probe' and resource 'LLMs for business/brand/product/topic visibility', clearly distinguishing from siblings like 'scan_competitor_ai_presence' which is narrower. Scope (0-100 score per model) and use cases are 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?

Description states when to use: AI-marketing audits, pre-launch checks, competitive monitoring. Explains optional _apiKey for Anthropic. Lacks explicit exclusion of alternatives but covers primary contexts well.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes beyond by explaining the routing process, citation format, and that it's a fast single call. It doesn't mention any side effects or error conditions, but given the annotations cover the safety profile, this is solid 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 lengthy but every sentence adds value: primary use, domain list, examples, default status, and escalation paths. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses paragraph structure effectively, so the length is justified by the tool's broad applicability.

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 compensates by explaining the return format (structured answer with citations). It covers the tool's role as a default entry point, its broad domain coverage, and when to escalate. Comprehensive enough for a general query-routing tool, though it doesn't detail response formatting edge cases.

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

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

Schema coverage is 100% and the question parameter description already clarifies aliases. The description adds example queries and reinforces that it accepts natural language, but doesn't add new semantic details beyond what the schema provides. Meets baseline for well-documented schema.

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

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

The description uses specific verbs ('Routes', 'returns', 'fills arguments') and clearly identifies the resource (5,529 tools across 1,455 verified sources) and output (structured answer with pipeworx:// citation URIs). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Explicitly gives both when-to-use ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...') and when-not-to-use alternatives ('Step up only when needed' to ask_pipeworx_grounded or deep_research). Even addresses breaking-news cases, making it the most actionable guidance possible.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds essential non-obvious context: the live candidate routing mechanism, that no candidate is active right now, and that results are compared against the stable router. This goes beyond annotations without contradicting them.

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

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

The description is information-dense, covering the tool's nature, current state, usage guidance, and a clarification in about four sentences. Every sentence contributes value; the 'falls back to nothing' line prevents a likely misconception. Slightly longer than strictly necessary but justified by the complexity.

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

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

Given the tool's simplicity (one question parameter, no output schema) and strong annotations, the description sufficiently covers experimental status, current behavior, and usage. It relies on referencing ask_pipeworx for response shape details, which is acceptable since that sibling exists, but it does not fully describe what routing improvements look like.

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 provides 100% coverage, fully describing the 'question' parameter and all six aliases. The description adds no parameter-level details beyond saying 'same arguments' as ask_pipeworx, which is not specific to this tool. Since the schema does the heavy lifting, 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 identifies this as a beta universal router with the same 5,529 tools and arguments as ask_pipeworx, and explicitly distinguishes it as the experimental edge with candidate routing improvements. The phrase 'Use it exactly like ask_pipeworx when you want the newest routing' reinforces the specific purpose.

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

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

The description states when to use this tool: when you want the newest routing, and notes it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router, but does not explicitly contrast with alternatives like ask_pipeworx_grounded or specify when NOT to use it.

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

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

Beyond the readOnlyHint=true annotation, the description discloses the grounding process, the explicit refusal mechanism with enumerated refusal_reason values, the return object structure, and the cost trade-off (one extra LLM call). This is substantial behavioral context that annotations alone do not convey, and it does not contradict any annotation.

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

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

The description is appropriately sized for the tool's complexity. It is front-loaded with the purpose, then builds context with routing, return format, refusal reasons, and usage guidance. Every sentence earns its place, with no redundancy or padding.

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 lack of an output schema, the description compensates fully by detailing the success response fields (answer, evidence, confidence, source, fetched_at) and the refusal response structure with possible reasons. It covers purpose, usage, behavior, and cost, making the tool well-understood 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 input schema covers all six parameters with 100% coverage, so the baseline is 3. The description does not add any parameter-specific details, but it does not need to since the schema fully documents the 'question' parameter and its aliases.

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 clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly differentiates itself from the sibling tool ask_pipeworx by noting the extra LLM call and the grounded extraction behavior, making the tool's unique value obvious.

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

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

It provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and also indicates when not to use it: 'prefer ask_pipeworx for casual lookups.' This directly addresses the when/when-not distinction with an alternative named.

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 annotations by detailing numerous behavioral traits: low-confidence resolution handling, closed market status, depth options, raw data toggling, cancellation rule parsing, rate limit fallback fields, and suppression of analysis on phantom matches. 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 lengthy but well-structured: purpose first, then input explanation, then detailed output shapes and edge cases. It is front-loaded with essential info. Minor redundancy in fan-out examples but acceptable given complexity.

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

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

Despite no output schema, the description thoroughly covers the return structure: market fields, analysis with model probability and edge, evidence keys, match confidence with alternatives, parent event for partition bets, news fields with fallback info, and safety/illiquidity notes. An agent has all information needed to use the tool effectively.

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

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

Schema coverage is 100%, and the description adds value for each parameter: it clarifies that 'market' accepts three formats (slug, URL, question text), explains 'depth' defaults to 'thorough', and specifies that 'include_raw' defaults to false and summarizes output size. This adds meaning beyond the schema descriptions.

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

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

The description clearly states the verb ('Research a Polymarket bet') and the resource (Pipeworx data). It specifies three input types (slug, URL, question text) and summarizes the output: evidence packet + market-vs-model comparison. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

It explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides fan-out examples and warns to inspect market_match_confidence before trusting analysis. However, it does not explicitly list when NOT to use, though sibling context implies 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, and idempotentHint. The description adds valuable behavioral context: it pulls real-time SEC/FAERS data, handles fiscal years correctly, sorts results, and returns citation URIs. This goes 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 informative but slightly verbose. However, it front-loads key trigger phrases and usage guidance. Nearly every sentence adds value, but a minor trim could improve conciseness.

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

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

Despite no output schema, the description explains the return format (paired data + citation URIs) and sorting behavior. Given the simple parameter structure and high schema coverage, the description is complete enough for correct agent invocation.

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

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

With 100% schema coverage, the description adds significant meaning: it explains the enum values (company vs drug), specifies how to format values (tickers/CIKs vs drug names), and limits array to 2-5 items. It also describes what data each type returns.

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 side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and lists trigger phrases, distinguishing it from single-entity 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases. It also explains data sources per type, guiding when to use each variant.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds far richer behavioral context: account sign-in requirement, paid tier for 'thorough', details of the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), explicit gaps[] never invented, contradictions[] in standard/thorough, semantic excerpting of large records, and expected latency. No contradiction with annotations.

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

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

The description is a dense single paragraph with many important caveats and details. Every sentence adds value (account requirements, alternatives, output format, gap handling, timing), so it earns its length, but the lack of structural formatting (bullets, labels) makes it harder to scan. It is appropriately sized for a complex tool, though slightly less concise than ideal.

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 values, and it does: findings packet, citations, gaps[], contradictions[], hop field, citation_uri, excerpting behavior, and latency expectations. It also covers account prerequisites and sibling tool guidance, making it fully complete for a tool of 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful semantics beyond the schema: it explains what each depth level does in terms of facets, hops, gap recovery, and the contradictions scan, and clarifies what kinds of questions are suitable for the 'question' parameter. This lifts the score to 4, though the schema already does solid 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 states a specific verb ('research'), a defined resource ('Pipeworx's 1455 STRUCTURED data sources'), and a clear method (decompose into facets, route to 5,529 tools in parallel). It explicitly distinguishes itself from siblings: 'this is NOT open-web search', and contrasts with ask_pipeworx for single lookups and breaking news.

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

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

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and names alternatives. It also covers account prerequisites and paid plan requirements, leaving no ambiguity about when to invoke this tool over siblings.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that results include full schemas with curated examples ready to call directly, and no second lookup needed, providing useful behavioral traits beyond the annotations.

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

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

The description is front-loaded with purpose and usage. It is somewhat long but every sentence adds value. Minor room for trimming 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?

No output schema, but the description fully explains the return format (names, descriptions, schemas, examples). It covers the tool's complexity and intention completely.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds meaning by listing query aliases and providing example queries, going beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing a data or task, listing many domains. It explicitly differentiates from siblings by positioning itself as a meta-tool to call first to see the option set.

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

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

The description explicitly says when to use: when needing to browse, search, look up, or discover tools, and directs to call FIRST. It lacks explicit when-not or alternative tools, which would raise it to 5, but the context is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds significant context: it fans out across multiple sources, specifies what is returned (cik, filings, fundamentals, patents with sunset note, news fallback, LEI), and mentions soft-failure for patents. No contradiction with annotations.

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

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

The description is dense but efficient, front-loaded with user-facing examples. Every sentence earns its place, covering purpose, usage, behavior, and limitations without fluff. It is well-structured for quick parsing.

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

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

Given no output schema, the description thoroughly explains return structure and data sources (SEC, XBRL, USPTO, GDELT/Gnews, GLEIF). It addresses limitations (patents sunset, name requirement). For a complex tool, it leaves no gaps for typical 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 100%, and the description enriches both parameters: 'type' is clarified as only 'company' currently, and 'value' specifies ticker or CIK format with a note that names are not supported, directing to another tool. This adds 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 uses clear action verbs ('Tell me about', 'research', 'brief me on') and explicitly states it returns a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself by advising to prefer it over chaining individual lookups, making its purpose distinct 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?

It provides explicit when-to-use ('holistic view') and when-not-to-use (names not supported, only company type). It directs users to use 'resolve_entity' for names, offering clear alternatives. The description also lists the exact data sources covered, aiding selection.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing 'sensitive data' and implies permanence, which is consistent and adds value 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?

Two sentences, no wasted words. The first sentence defines the action, the second provides usage context. Highly 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 one simple parameter, full schema coverage, and no output schema, the description covers everything needed: what, when, and how it relates to siblings. Complete for a memory deletion 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 a clear description of the 'key' parameter. The description adds 'by key' but does not provide additional semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb+resource pair. It distinguishes itself from siblings by mentioning 'Pair with remember and recall.'

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with sibling tools.

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

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

The description adds behavioral context beyond annotations by disclosing that the tool fetches an external URL and extracts content. Annotations already indicate read-only, idempotent behavior; the description clarifies the outbound call aspect, but lacks details on error handling or fetch failures.

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

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

The description is concise with three sentences: purpose, process, use cases. It is front-loaded and contains no fluff, earning its place efficiently.

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 covers purpose, parameters, and output format adequately. Minor gaps exist, such as omission of error behavior or exact output type, but overall it is sufficiently complete for this context.

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

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

Schema coverage is 100%, so the parameters are already well-documented. The description does not add new meaning beyond what the schema provides for 'url' and 'max_links', staying at the baseline for schema-rich tools.

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, specifically for AI crawlers. It details the process (fetch, extract, emit) and output format, distinguishing it from any sibling tools.

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

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

The description lists explicit use cases (client indexing, personal projects, competitor auditing), providing clear guidance on when to use. However, it does not mention alternatives or when not to use the tool, missing some comparative context.

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

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

Adds value beyond annotations by specifying scope ('caller's'), return fields, and the active/inactive distinction implied by the include_inactive parameter. 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?

Two efficient sentences with front-loaded verb-resource-object structure, zero 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?

Despite no output schema, the description lists all relevant return fields and includes usage guidance, fully covering the tool's behavior for a simple list operation.

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

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

Schema coverage is 100% with the include_inactive parameter fully described; the description does not add additional semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, mentions returned fields, and is distinct from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel', giving clear context for when to invoke.

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, covering safety. The description adds the behavioral constraint of exact-name matching, which is not in annotations, thus providing additional 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 extremely concise (one sentence) with no extraneous content. Every word is purposeful.

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, annotations, and presence of output schema, the description provides all necessary context. Agent can correctly select and invoke the tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description only restates 'artist, title pair' without adding new details beyond schema, so baseline score applies.

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

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

The description uses specific verb 'returns' and resource 'lyrics text', clearly stating the tool does an exact-name lookup for an artist-title pair. It is unambiguous and sets clear expectations.

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

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

The phrase 'Exact-name lookup' implicitly tells the agent when to use this tool (exact match) and when not (fuzzy or partial matches). No explicit alternatives are given, 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 are all false, providing minimal behavioral signal; the description compensates by disclosing rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow for anonymous reports, and that the team reads digests daily and signal affects roadmap. It also clarifies the tool doesn't count against the tool-call quota.

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 long, unbroken paragraph but dense with necessary context; every sentence introduces a new detail (usage categories, exclusion, token flow, rate limit, quota). It is front-loaded with the core purpose, though the multi-clause structure makes it less scannable than a structured list.

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

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

The tool is complex (requires exclusions, token mechanics, rate limits), but the description covers all required context: when to use, how to frame feedback, what the claim_token does, and rate limits. No output schema exists, but the description explains what filing returns (a claim_token) and how to use 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?

The schema already describes all four parameters at 100% coverage, but the description adds usage semantics beyond the field descriptions: it demonstrates the claim_token call syntax ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts.

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 clear imperative 'Tell the Pipeworx team something is broken, missing, or needs to exist,' establishing the tool's purpose as feedback for Pipeworx. It explicitly distinguishes itself from sibling tools by stating it only handles tools from this Pipeworx connection, not connectors from other MCP servers, and names the categories (bug, feature/data_gap, praise).

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 guidance: 'Use when a tool returns wrong/stale data (bug)...' and also provides an exclusion: if the tool came from a different MCP server, file with that server instead. It further clarifies 'Pipeworx tool names are the ones this connection lists' to disambiguate from siblings.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds that data is self-aggregated from CF analytics-engine, contains no PII, and is cached 5min-1h. This provides valuable behavioral context.

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

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

Every sentence earns its place: purpose, use cases, and implementation details are packed concisely with no filler. Front-loaded with the primary function.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains what it returns, how it works, and its utility. No gaps.

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

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

Schema coverage is 100% with enum descriptions. The description adds minor nuance about window effects (short vs. steady-state) but does not significantly expand on schema-provided info, meeting baseline expectations.

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

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

The description clearly states the tool returns 'the top tools, top packs, and total call volume over a recent window.' It specifies the action and resource, distinguishing it from sibling tools that perform other functions like asking questions or researching entities.

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

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

Three explicit use cases are provided (discovering hot sources, confirming canonical choice, seeing alignment) along with window selection guidance. While it lacks explicit when-not-to-use advice, the context is sufficient for agent decision-making.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds deep behavioral context: monotonicity violations, partition checks, semantic anchor, placeholders filter, fill check details. No contradiction.

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

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

Description is long but well-structured with clear sections and examples. Every sentence adds value, though slightly verbose.

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 thoroughly explains return structure (opportunities[], partition_check, fill check fields) and provides enough context for an agent to correctly interpret results.

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

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

Schema coverage 100%, description adds usage context beyond schema: explains accepted formats (event slug, URLs) and provides examples for both 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?

Clear verb (Find arbitrage opportunities) and resource (Polymarket) with distinct modes (event, topic) that differentiate from siblings like 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?

Explicit when-to-use for each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Also provides fill check and when not to trade.

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, idempotentHint, etc.) are consistent. Description adds extensive behavioral detail: caching at KV level, edge calculations after slippage, Kelly caps, 24h-move warnings, Fed bet exclusion. 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 thorough but verbose, resembling full documentation. It is front-loaded with purpose but includes extensive model details that could be separated. Not concise, yet each sentence serves a purpose.

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

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

For a tool with complex behavior (9 parameters, no output schema, three segments), the description covers all aspects: model families, response structure, caching, diagnostics, and parameter interactions. It leaves no ambiguity for correct invocation.

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

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

Schema coverage is 100% so all parameters are described. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and the min_partition_leg_kelly behavior in depth, going beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It distinguishes from siblings by detailing three specific model segments.

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?

Usage context is implied (betting opportunities) and tradeable-edge knobs are explained, but no explicit comparison or when-not-to-use guidance is given relative to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds substantial behavioral context: data source (daily snapshots, 60-day TTL), response structure (tracked, expired, snapshot_dates), and decay computation details. No contradictions with annotations.

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

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

The description is lengthy and detailed, which provides completeness but sacrifices conciseness. It has clear structure (purpose, response, limits) but some sentences are verbose. Could be tightened without losing information.

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

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

No output schema exists, so the description thoroughly explains return values: tracked[] with time-series, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers limits and data sources, making the tool self-contained for an AI agent.

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

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

Schema covers both parameters with descriptions. The description adds context: defaults (days=14, window='1wk'), clamp ranges (days 2-30), and explanation of window as snapshot family. This enriches schema meaning beyond baselines for 100% 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 it provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed. This verb+resource is specific and distinct from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description explains when to use this tool (to differentiate fresh vs. old edges) and implies it for decay analysis. However, it does not explicitly state when not to use it or name alternatives, missing some explicit 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 goes far beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing how the tool walks the order book ladder, returns specific fields for single-market and basket modes, identifies thin legs, and describes 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 dense but necessary given the tool's complexity. It could benefit from more structured formatting (e.g., bullet points), but all information is present and well-organized with clear sections for single-market and basket modes. No wasted sentences.

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

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

Despite lacking an output schema, the description fully explains all return fields for both modes, including edge cases like thin legs and forced directional risk. The tool's usage context, inputs, and outputs are thoroughly covered for its intended purpose.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the different interpretations of size_usd for single-market vs basket, the default side logic for basket mode, and examples of return values. This extra context justifies a 4.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes single-market and basket modes, and its role as a pre-action check for arb signals or large trades. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about partial fills and unhedged directional risk. While it gives clear context for when to use, it does not explicitly list scenarios when not to use beyond the threshold, making it slightly incomplete.

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 annotations (readOnly, idempotent, non-destructive). It details two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains when spreads are meaningless. This level of behavioral transparency is exemplary.

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: starts with purpose, then modes, response, safety fields, and cautionary note. Every sentence provides useful information. Minor improvement: could use bullet points for modes and safety fields for easier scanning, but it's still effective.

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

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

Given the complexity of cross-venue spread computation, the description covers all essential aspects: modes, parameters, response fields, edge cases (compatibility, temporal misalignment), and limitations (pre-mapped not always tradeable). No output schema exists, but the description compensates well with verbal explanation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes, that topic provides shortcuts, and that explicit parameters override the topic. It gives examples and clarifies parameter interactions. This is more than just restating schema.

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

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

The description clearly states the tool's core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than intra-venue opportunities. The two modes and response details further clarify purpose.

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

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

The description provides clear context on when to use (to get spreads between venues) and when not (compatibility_warning indicates no arb, temporal misalignment). It notes that real spreads are rarer than the shortcuts suggest. Although it doesn't explicitly name alternatives, the context is sufficient for an agent to decide. An explicit comparison to polymarket_arbitrage would elevate it to 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, idempotentHint=true, destructiveHint=false. The description adds useful context: scoping to an identifier and pairing with remember/forget. No contradictions.

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

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

Description is concise (three sentences) and front-loaded with core purpose. Every sentence adds value; no wasted words.

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

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

For a retrieval tool with one optional parameter and no output schema, the description fully covers behavior: retrieval vs listing, scoping, and pairing with siblings. No gaps.

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

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

Schema coverage is 100% with a clear parameter description for 'key'. The description reiterates that omitting key lists all keys, adding no new information 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 explicitly states the action ('Retrieve a value previously saved via remember, or list all saved keys') and specifies the resource (a saved memory key or list of keys). It distinguishes from sibling tools like 'remember' and 'forget' by contrasting retrieval with save/delete.

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?

Usage context is clear: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It implicitly excludes saving (remember) or deleting (forget) and mentions scoping to identifier.

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 behavioral context: explains the return fields (source, citation_uri, payload), the effect of mark_read, and mentions an alternative access endpoint. No contradictions.

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

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

Three sentences with the main purpose first, followed by return details and key parameter notes. No redundant information; every sentence adds value. Highly efficient.

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

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

The description covers the main output fields, filter capabilities, mark_read behavior, and provides an alternative access method. With no output schema, it adequately describes return format. Missing explicit mention of unread_only parameter behavior, but overall 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?

Input schema covers all 5 parameters with descriptions (100% coverage). The description adds examples for type ('sec_8k') and since (ISO timestamp), and explains mark_read behavior, but does not mention limit or unread_only. Baseline of 3 is appropriate since schema does heavy lifting.

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 'Pull fired events from your subscription feed' and 'Returns the most recent alerts', defining the tool's verb and resource. It implicitly distinguishes from siblings like list_subscriptions by focusing on alerts rather than subscriptions, but does not explicitly differentiate.

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

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

The description provides usage context ('Polls work fine') and examples of filtering by type and timestamp, but does not explicitly state when to use this tool over alternatives or when not to use it. No comparative guidance against siblings like list_subscriptions or search_within.

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 details the behavior beyond annotations: fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains fallback and rate-limiting, mentions a soft-fail for USPTO, and describes the return format. Annotations already indicate read-only and idempotent, but the description adds rich behavioral context.

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

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

The description is well-structured: front-loaded with example queries, then explains sources, parameters, return format, and alternative. Every sentence adds value; no redundancy or fluff.

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

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

Given the tool's complexity (multiple data sources, fallback, no output schema), the description is highly complete. It covers sources, parameter formats, return structure, error handling, and provides an alternative tool. An agent can confidently select and invoke this 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% (all 3 parameters described). The description adds value by providing examples for 'since' (ISO date or relative) and explaining 'value' can be ticker or CIK. It also clarifies that 'type' only supports 'company'. This goes beyond the schema's 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 verb-resource: 'change feed for a company in the last N days/weeks/months'. It provides example queries that distinguish it from sibling tools like entity_profile, and explicitly mentions the alternative for static profiles.

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

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

The description explicitly states when to use this tool (recent changes with a time window) and when to use the alternative entity_profile (static profile). It also gives example queries and acceptable parameter formats.

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 the tool is non-destructive and idempotent. The description adds valuable context about scope (scoped by identifier) and persistence (persistent for authenticated users, 24-hour for anonymous sessions).

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?

Five concise sentences, each earning its place. Front-loaded with purpose, efficient examples, and clear pairing guidance. No redundancy.

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

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

Given two simple parameters with full schema coverage and no output schema, the description provides all necessary behavioral context: storage mechanism, scope, retention policy, and usage along with related 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?

Both parameters are fully described in the schema. The description goes beyond by giving practical key examples (e.g., 'resolved ticker', 'user preference') and clarifying the value can be 'any text', adding real-world context.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using a specific verb and resource. It distinguishes from siblings by naming recall and forget as complementary 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 tells when to use ('when you discover something worth carrying forward'), provides concrete examples, and directs to pair with recall and forget for retrieval and deletion.

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

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

The description adds significant detail beyond annotations: it cascades through multiple lookup endpoints, degrades gracefully (EDGAR still returns if GLEIF/OpenFIGI unavailable), labels identifiers with sources, and explicitly states unresolved identifiers under `unresolved`. This is rich behavioral transparency that goes beyond the readOnly/openWorld/idempotent 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 well-structured: example queries first, then usage guidance, then per-type details. Every sentence adds value, though the opening example list is slightly verbose. It earns a 4 for being thorough without fluff.

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

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

Given that there's no output schema, the description effectively covers return behavior (identified/unresolved, labelled sources) and failure modes (graceful degradation). It fully addresses a 2-parameter tool with two types, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both `type` and `value`. The description enhances this by explaining the cross-source identity spine for companies and the RxNorm citation for drugs, adding real-world context about what each type returns and what input formats are accepted. This is above 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 resolves user-spoken names to canonical/official identifiers, with specific verbs (resolve, find, look up) and examples like ticker, CIK, LEI, RxCUI. It distinguishes itself from siblings by positioning as the first step when an ID is needed, not a deep-dive tool like entity_profile or compare_entities.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use. It also differentiates between company and drug types with input examples. However, it doesn't explicitly mention when not to use it or name alternative tools, so it misses full exclusion guidance.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context that the tool probes each entity with ai_visibility_check, aggregates results, and returns a ranked list. It does not contradict annotations. It could further mention potential rate limiting or data freshness, but overall it informs well 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 extremely concise, consisting of two well-structured sentences. The first sentence states the core function, mechanism, and output; the second provides a concrete use case and example. No unnecessary words, fully 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?

Despite lacking an output schema, the description fully explains the returned information (ranked list with score, confidence, signal density per entity). It covers the workflow (calling underlying tool, ranking), the use case, and the number of entities. Given the tool's complexity, this is complete enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for the 'entities' parameter, noting the first entry is treated as the 'subject' for narrative. It also clarifies that 'models' and 'context' are optional and that '_apiKey' is only needed for Anthropic. This enriches the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces the most/least recognized. It distinguishes from the sibling ai_visibility_check by explicitly mentioning the multi-entity comparison and competitive audit 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 clear context for use ('useful for competitive AI-marketing audits') and an example question. It implicitly contrasts with the single-entity tool ai_visibility_check but does not explicitly state when not to use or compare with other relevant siblings like compare_entities. However, the guidance is sufficient.

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

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

Description adds behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, 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?

Description is dense but well-structured: purpose first, then usage, return details, limitations. Every sentence adds value with 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?

Despite no output schema, description details the return structure (summary block, per-advisory, links, alternative versions). Covers ecosystem limitation, partial failure, and performance characteristics. Fully complete for a composite query tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds context: default version to latest, scoped packages accepted. Baseline 3 plus extra context justifies 4.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package. It specifies the verb 'check' and the resource 'npm package', and distinguishes from sibling tools like deps.dev:version for other ecosystems.

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

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

Explicitly says to use when an agent asks about safety, popularity, size, or cost of a dependency. Also notes that other ecosystems fall under deps.dev:version directly, providing clear when-to-use and alternative 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?

Discloses internal behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. This goes beyond annotations which already provide readOnlyHint, idempotentHint, etc. 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?

Four sentences, each essential. Front-loaded with core purpose, then usage, then technical details. No redundancy or fluff.

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

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

The description covers functionality, use case, pairing, algorithm, limits, and output format, making it fully actionable despite no 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 description coverage is 100%, so baseline is 3. The description adds value by providing example queries for the 'query' parameter and clarifying the truncation behavior for 'text'. The limit parameter is mentioned in the output description.

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 inside' a fetched record, specifies the resource (text), and describes the output (top-N passages with offsets and similarity scores). It distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded.

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 how it saves context. Also provides guidance on pairing with ask_pipeworx_grounded for grounding over relevant passages.

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

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

Adds behavior beyond annotations: returns subscription id, SMS rate cap (10/day), webhook auto-disable after 10 failures. 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?

Dense and well-structured, but slightly long. Front-loads purpose and prerequisites. Every sentence adds value.

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

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

Given complexity and no output schema, description covers prerequisites, type options, delivery details, and constraints, making it complete.

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

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

Schema coverage is 100%, but description adds valuable context and examples for each parameter, including nested objects and enums, enhancing 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly mentions requirement of Pipeworx OAuth account and supported types. Does not directly state when not to use, but provides clear context and prerequisites.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds minimal behavioral context (returning track+artist info) beyond the annotations. 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 12-word sentence, highly concise and front-loaded. It could be slightly more structured (e.g., bullet points) but is efficient.

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

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

With an output schema present, return values are documented. The description covers input (free-form query) and output (track+artist info) adequately for a simple suggestion tool. Could mention scope or edge cases, but it's generally sufficient.

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% (only 'limit' has description). The description explains 'query' as 'free-form query', adding some context, but does not elaborate on 'limit' beyond its schema description. Baseline 3 is appropriate given partial 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 ('suggest'), the resource ('Title/artist suggestions'), and the input context ('free-form query'), while also noting the output includes track and artist info. This effectively distinguishes it from sibling tools like 'lyrics' or 'search_within'.

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

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

The description implies usage for open-ended music queries but does not explicitly state when to use this tool versus alternatives (e.g., 'lyrics' for lyrics, 'search_within' for other searches). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it returns categorized example questions with tool+argument shapes, and explains the effect of the topic parameter. 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 relatively long but front-loaded with common queries and each sentence adds information. It is well-structured and not overly verbose for the amount of context provided.

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

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

Given no output schema and one optional parameter, the description is fairly complete. It explains what the output contains (category-bucketed examples with tool shapes) and how to focus via topic. It does not need further elaboration.

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% for the single parameter 'topic'. The description goes beyond by explaining the effect of omitting vs providing the parameter, and lists possible values. This adds semantic clarity.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like 'suggest' by focusing on what Pipeworx can do and listing specific use cases.

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

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

The description explicitly says to use this tool FIRST when you don't know what Pipeworx can do, and to learn how to call meta-tools. It provides context via examples but does not explicitly state when not to use it, though the guidance is clear.

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

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

Discloses that the row is deactivated (not deleted) and that historical events remain available via recent_alerts, adding 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?

Two concise sentences with the action stated first; 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 the main points for a simple tool: action, ownership, and side effect. No output schema needed, but error cases are not mentioned.

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

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

Schema coverage is 100% and the description uses 'by id' but does not add significant meaning beyond the schema's own parameter description.

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 'Cancel a subscription by id' with a specific verb and resource. It 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?

States ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear guidance on when it can and cannot be used.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses behavioral traits: it returns a defined set of verdicts, includes a pipeworx:// citation, and crucially explains that could_not_verify means the check did not happen and must not be treated as evidence. This is a critical caveat beyond any annotation. It also notes the fall-through pipeline and structured fast path.

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

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

The description is dense but well-structured: trigger phrases first, then purpose, routing, output format, and a clearly marked 'IMPORTANT' callout. No filler sentences; every part earns its place given the tool's complexity.

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

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

With no output schema, the description fully covers return values (verdicts, actual value, citation, reasoning) and handles edge cases explicitly (could_not_verify vs unsupported). It also explains the two execution paths, making it sufficiently complete for an agent to use correctly.

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

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

The description adds meaning to both parameters: it gives examples of natural-language claims and explains the role of tolerance_pct in grading and hallucination detection. This goes beyond the schema descriptions, which are already detailed.

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 'natural-language claim verification against authoritative sources' with specific trigger examples and a distinct resource (the claim). It also distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls, making its purpose unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and details routing for company-financial vs other claims. However, it does not explicitly name alternative tools or exclusions, so it stops short of full when-not guidance.

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