Seatgeek

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds beyond that: the default model (Workers AI Llama-3.3-70b) is free, while probing Anthropic requires a BYO API key with direct billing, and it outlines the return structure per model. This enriches the agent's understanding without contradicting annotations.

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

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

The description is three sentences, front-loaded with the core action, then covering defaults, cost, return format, and use cases. Every sentence adds value; no redundancy or filler.

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

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

Despite no output schema, the description explicitly lists the per-model result fields ('{score, confidence, signals, raw_response} + a combined view'). It also covers default behavior, cost, and practical use cases. Given the tool's moderate complexity, this is complete enough for an agent to select and invoke it confidently.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying the default model for the 'models' parameter and the cost implication of supplying '_apiKey'. This goes beyond the schema descriptions, which already explain the parameters well.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's function and distinguishes it from siblings like scan_competitor_ai_presence by focusing on direct LLM probing and scoring.

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

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

The description provides clear use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly name alternatives or exclusion criteria, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral context: it routes to tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and notes it works on every tier with one fast call. It doesn't contradict annotations and adds useful operational details beyond what annotations provide, though it doesn't discuss failure modes or rate limits.

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

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

The description is front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and organizes content into logical sections: purpose, usage triggers, examples, alternatives, and a final note on news. However, it is verbose, with redundancy like repeating 'START HERE' and listing many categories that could be condensed. The length is justified by the need to cover many source types and alternatives, but a more streamlined version would be tighter.

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

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

For a tool with no output schema and a wide-ranging purpose, the description covers what it does, when to use it, examples, alternatives, and notes the return format (structured answer with citation URIs). It lacks explicit detail on the exact response schema, but given the tool's breadth, specifying a single output format would be impractical. The description gives sufficient context for an agent to know when to call it and what to expect, though a note on potential errors or limits would make it more complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already documents (the question field with aliases). It does provide domain examples (Apple revenue, SEC filings, bitcoin price) that illustrate usage, but those are already in the schema's examples. No compensation needed for low coverage.

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

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

The description states a specific purpose: answer factual questions about real-world data with citations, routing to 5,635 tools across 1477 sources. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with different use cases. The scope is well-defined (SEC filings, FDA, FRED, etc.) and uses specific verbs like 'routes', 'returns', 'fills arguments'.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'). It also provides when-to-step-up for alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions) and notes news coverage. The instruction 'START HERE for most questions' gives clear prioritization.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical context beyond these: it is an experimental beta with possibly active routing improvements, currently no candidate is active, it matches ask_pipeworx exactly, and it is a full working router (not a fallback). This informs the agent of the current and potential behavior, which annotations cannot convey.

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

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

The description is slightly verbose but every sentence serves a purpose: it introduces the beta nature, clarifies current state, gives usage guidance, and dispels a misconception about fallback. Information is front-loaded, but it could be tightened without losing meaning.

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 is largely self-sufficient: it explains the tool's role, its current state, and directs the user to use it exactly like ask_pipeworx, which is a sibling. It does not describe the response format, but that is inherited from ask_pipeworx and is likely documented there. Given the annotations cover safety and the tool points to a sibling for full details, it is fairly complete.

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

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

Schema description coverage is 100% and the schema clearly documents all aliases for the 'question' parameter. The description adds no parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate per the guidelines.

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?

States it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. This clearly identifies the tool's function (routing questions across 5,635 tools) and distinguishes it from the stable ask_pipeworx by explicitly naming that sibling.

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 the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implies the alternative (use ask_pipeworx for stable routing) and explains that results are compared to the stable router. This gives clear decision criteria.

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

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

Even though annotations (readOnlyHint, openWorldHint, idempotentHint) are present, the description discloses significant behavioral traits beyond them: the grounded extraction mechanism, the structured response with evidence/confidence, the explicit refusal reasons, and the extra LLM cost. 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 dense but every sentence contributes: core purpose, mechanism, return format, refusal handling, usage guidance, and cost tradeoff. It is front-loaded with the defining attribute and ends with actionable routing advice. No filler or redundancy.

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

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

Despite no output schema, the description explicitly details the success and refusal response shapes, including all refusal reason enums. It covers when to use, how it differs from the sibling, and the cost implication. For a tool with this complexity, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, with all aliases documented in the schema itself. The description adds no parameter-specific detail beyond 'Your question in natural language,' which repeats the schema. With full schema coverage, baseline is 3, and there is no extra value from the description here.

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 ('answer mode'), a distinctive attribute ('Hallucination-resistant'), and clearly differentiates from the sibling 'ask_pipeworx' by naming it and noting 'Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains.' This makes the tool's purpose unambiguous and distinct.

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

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

Explicitly states when to use (high-stakes reads, quoted/cited/acted-on answers, must not invent facts) and when to prefer the alternative ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'). This is precise routing guidance with clear conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description goes far beyond by detailing fan-out behavior, resolver match confidence levels, short-circuiting on low-confidence matches, handling of closed markets, wide-spread illiquidity, and cancellation rule parsing. 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 but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the primary purpose in the first sentence, and each section contributes unique operational details without fluff, though it is at the upper bound of acceptable length.

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

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

With no output schema, the description takes full responsibility for explaining return values and behavior. It covers response shapes (market, analysis, evidence), resolver contract with match confidence scores and alternatives, parent event extractor for partition bets, news fallback fields, safety statuses, and resolution-rule risk. This is comprehensive 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?

Schema coverage is 100% so the baseline is 3, but the description adds meaningful semantics: it explains the market parameter accepts slug/URL/question text, clarifies depth enum values ('quick = 2-3 evidence sources, thorough = full fan-out'), and describes include_raw's size implications ('keeps responses under ~20KB' vs '50KB-500KB'). It also provides concrete fan-out examples that link parameter choices to data sources.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' providing a specific verb, resource, and scope. It also distinguishes itself from sibling tools like ask_pipeworx and validate_claim by focusing on Polymarket bets with data packs, and lists example use cases like 'should I bet on X' and 'is there edge in Z'.

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 clearly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides practical guidance like 'Check this before sizing sports/esports/event-occurrence bets' for cancellation rules. However, it does not explicitly mention when not to use the tool or directly compare with alternatives, so it lacks exclusions.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses important behavioral details: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, parallel execution, and the return format (paired data + citation URIs). This adds substantial transparency without contradicting 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 compact yet dense. It opens with example queries, then states core behavior, preference, per-type details, and return format. Every sentence adds value, and the structure is logical (from general to specific, then output summary). No redundant or filler text.

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

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

The tool has no output schema, but the description compensates by explaining the return format ('paired data + pipeworx:// citation URIs per entity') and the sorting behavior. It also covers edge cases (off-calendar fiscal years), data sources, and the scope (2–5 entities). For a comparison tool of this complexity, the description is sufficiently complete for an agent to select and invoke it correctly.

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

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

The schema already covers both parameters (type and values) at 100%, but the description adds significant meaning: for type, it explains what each enum value pulls (revenue/net income/cash/debt for companies; adverse-event counts/approval counts/trial counts for drugs). For values, it gives concrete examples and reinforces the 2–5 range. It also clarifies the output behavior (sorted by primary metric), enriching the semantic understanding beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one call. It uses specific verbs ('compare', 'rank', 'head to head') and a specific resource ('companies or drugs'). It also distinguishes from sequential lookups, explicitly positioning itself as the preferred alternative for comparisons, which satisfies sibling differentiation even without naming a tool.

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 strong when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups.' It also clarifies usage by type (company vs drug). However, it does not explicitly state when not to use the tool (e.g., for single entity lookups) or name a specific alternative tool, so it lacks full exclusion coverage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these, disclosing latency (15-60s, up to ~90s for thorough), parallel decomposition into facets, gap handling with explicit gaps[], contradictions[] scanning, excerpting behavior (semantic excerpts of large records), citation URI fetchability guarantees, and hop fields. Nothing contradicts the annotations, and the description enriches them with operational behavior in detail.

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?

Though long, the description is tightly packed with critical information and structured logically. It front-loads the account requirement, then differentiates from alternatives, explains the research process, details depth options, and ends with latency expectations. Every sentence earns its place; there is no filler. The length is justified by the tool's complexity and the lack of an output schema.

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

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

For a tool with no output schema, the description fully covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[]), the depth parameter semantics, latency, and edge cases (untracked topics leading to empty gaps). The agent is equipped to call the tool correctly, interpret results, and handle failure modes. Nothing essential is missing.

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

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

Schema coverage is 100% (both question and depth are documented in the schema), but the description adds substantive meaning beyond the schema. It explains the depth enum in detail (quick=3 facets, standard adds gap-recovery + contradictions, thorough adds lead-chasing), clarifies that 'question' can be broad/multi-part ('decomposition is the point'), and gives guidance on how to phrase it. This is a strong example of description adding value over structured fields.

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

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

The description states a specific verb and resource: 'grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources' and explicitly says it is NOT open-web search. It distinguishes itself from siblings by naming ask_pipeworx as the alternative for single lookups and live news. The purpose is unambiguous and clearly differentiated.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS / "what's the world saying about X" topics, prefer ask_pipeworx'. It also mentions account requirements and the fallback for signed-out users. This is the gold standard for routing agents to the correct tool.

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

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

Annotations already declare readOnly/idempotent, and the description adds valuable context: returns top-N tools with names, descriptions, and full input schemas with curated examples, ready to call directly. No contradiction with annotations. It doesn't cover edge cases or rate limits, but for a read-only search tool this is sufficient.

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

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

The description is front-loaded with purpose, then usage, then return behavior. It is somewhat long due to the domain list, but each sentence adds value. The structure is logical and easy to scan, though it could be tightened slightly 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?

Despite no output schema, the description explicitly states what is returned ('names, descriptions, and full input schemas with curated examples') and emphasizes that results are ready to call directly. It also explains the tool's role as a first step for discovery, making it complete for its simple 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 the baseline is 3. The description does not redefine parameters but adds domain examples and clarifies the query is a natural language task description. This aligns with schema but provides no additional parameter semantics beyond what's already documented.

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 'Find tools by describing the data or task' with a specific verb and resource, and distinguishes itself from sibling tools by positioning as a meta-discovery tool. It lists concrete domains (SEC filings, FDA drugs, etc.) and explains that it returns top-N tools, 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 says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly communicates when to use it versus alternatives, though it doesn't name specific alternative tools.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds rich behavioral detail beyond annotations: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific return fields; patent soft-fail due to USPTO PatentsView sunset; GDELT→GNews fallback; and filing URI format. No contradiction with annotations.

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

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

The description is long but dense, front-loaded with example intents and then structured into source fan-out, return fields, fallbacks, and parameter constraints. Every sentence provides unique value, though the list of example phrasings could be slightly trimmed without losing clarity.

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

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

Since there is no output schema, the description fully compensates by enumerating return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI), sources, constraints, and failure modes. It gives the agent all needed context for invocation and expectation setting.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents both parameters (type and value) with examples. The description repeats the ticker/CIK requirement and the 'names not supported' note but adds no new parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly defines the tool as a full cross-source profile of a US public company executed in one parallel call, using specific verbs like 'tell me about', 'research', and 'brief me'. It distinguishes itself from siblings by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing users to resolve_entity for name-only inputs.

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

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

The description provides explicit when-to-use guidance via example intents and a preference rule for holistic profiles. It also gives a clear exclusion: 'names not supported — use resolve_entity first if you only have a name', covering both when and when-not scenarios with an alternative.

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 idempotentHint=true, setting a safe read baseline. The description adds value by disclosing the exact details returned (venue, performers, datetime, ticket counts, prices), which goes beyond annotations. 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?

A single concise sentence that front-loads the action and resource, then lists the key return contents. Every word earns its place with no fluff or repetition.

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

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

For a simple single-id read tool, the description is fully complete: it states the input, the output scope, and the specifics of what is returned. The output schema exists, so return values are structured, and annotations cover safety. Siblings like 'events' handle list/search, leaving this tool's niche clear.

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

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

The input schema has only one parameter 'id' with type number and 0% coverage (no description). The description clarifies that this is a numeric SeatGeek event id, adding meaning beyond the schema. However, it doesn't explain how to obtain the id or any constraints, so it partially compensates for the missing schema 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 tool fetches full details for a single SeatGeek event by numeric id, and enumerates specific content (venue, performers, datetime, ticket counts, prices). This specific verb and resource clearly distinguish it from siblings like 'events' (plural) or 'performers'.

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 this tool is for when the agent has a specific numeric event id and needs comprehensive details, as opposed to searching or listing. It doesn't explicitly name alternative tools like 'events' for search/list, but the singular nature and mention of 'single' provides clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context by listing the return fields, but it does not disclose pagination behavior, default ordering, or any edge cases like how q is fuzzy vs performers.slug exact (the latter is only in the schema). The bar is lowered by annotations, but the description adds only modest behavioral context beyond the safety annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys the search dimensions and return type. It is concise, well-structured, and every clause adds value—no filler or redundancy.

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

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

With 11 optional parameters, 100% schema coverage, an output schema, and strong annotations, the description is largely sufficient. It covers the primary purpose and capabilities. However, it does not mention default behavior when no filters are provided (e.g., returning popular events) or explicitly note pagination, which are minor gaps for a search 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?

Schema description coverage is 100%, so the schema fully documents each parameter. The description's mention of 'keyword, venue, performer, location, date range, or category' maps to the parameters but adds no new semantics beyond what the schema already says. Baseline 3 is appropriate since the schema already provides detailed parameter meanings and examples.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Search SeatGeek events' followed by a list of search dimensions (keyword, venue, performer, location, date range, category). It also mentions the return payload (event listings with name, datetime, venue, performers, ticket URLs), which distinguishes it from the sibling 'event' tool likely used for fetching a single event.

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

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

The description provides clear context for when to use the tool: whenever you need to find events matching various criteria. It implies use for search scenarios, but it does not explicitly contrast with the sibling 'event' tool (e.g., 'use events to search, use event to get details by ID'). The plural 'events' and focus on search are implicit differentiators, but explicit exclusions are missing.

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 destructiveHint=true and idempotentHint=true, and the description aligns by saying 'Delete'. It adds useful context about what kinds of memories to forget (stale, sensitive) that goes beyond the annotations, but no major additional behavioral details are disclosed.

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

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

Two sentences, front-loaded with the action, then usage guidance. Every word earns its place; no padding or repetition.

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

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

For a one-parameter delete operation with strong annotations (destructive, idempotent) and no output schema, the description fully covers purpose, usage, and key semantics. Nothing critical is missing.

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

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

The input schema fully documents the single 'key' parameter with a description ('Memory key to delete'). The description merely restates 'by key' without adding extra meaning, so it does not exceed the baseline for full schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb (delete) and resource (memory). This distinguishes it from sibling tools like remember and recall, which handle storing and retrieving memories.

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

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

Provides explicit usage scenarios (stale context, task done, clearing sensitive data) and mentions pairing with remember and recall. However, it does not explicitly state when not to use the tool or name direct alternatives, so it misses the highest bar.

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 (readOnly, openWorld, idempotent) already cover safety, and the description adds meaningful behavioral context: it 'fetches the page' (indicates network access) and 'emits the standard llms.txt markdown format' (describes output). It does not disclose error details or rate limits, but the annotations lower the bar.

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

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

The description is efficiently structured: purpose, mechanism, output format, and use cases in three sentences. Every clause adds value, with no fluff or repetition.

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

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

Given the rich annotations, complete schema, and no output schema, the description fully covers what the tool does, how it works, and what the output looks like ('single text blob ready to drop at site-root/llms.txt'). This is sufficient 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%, so the baseline is 3. The description adds only marginal parameter insight (e.g., 'standard llms.txt markdown format' and 'single text blob'), while the schema already documents url and max_links with defaults and limits.

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 a specific verb ('Generate') and resource ('llms.txt file for any URL'), and clearly states the function: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This distinguishes it from siblings like scan_competitor_ai_presence by focusing on producing the llms.txt file itself.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context, though it does not explicitly name alternative tools or exclusions, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, providing a strong safety profile. The description adds valuable behavioral context by listing the returned fields and clarifying that it operates on the caller's own subscriptions, which is useful 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 two concise sentences with no redundancy. The first sentence states the core action and output fields; the second provides usage context. Nothing extraneous.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is sufficient. It covers purpose, usage, return fields, and scope, while annotations handle the safety profile.

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 fully describes the single parameter include_inactive with its default behavior. The tool description does not add parameter-specific details, so the baseline of 3 applies given 100% schema 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 uses a specific verb 'list' plus a clear resource ('subscriptions') scoped to 'the caller's active' ones, and lists the exact fields returned. This clearly distinguishes it from siblings like subscribe/unsubscribe, which perform mutations on 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?

The description explicitly states when to use the tool: 'before adding more' subscriptions and 'to find an id to cancel.' It implies the alternatives (subscribe/unsubscribe) but does not name them directly or provide a when-not-to-use statement, so it misses the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes beyond annotations by specifying the response contents (bio, images, taxonomies, stats, related performers), which sets expectations. 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?

A single sentence with a clear verb and resource, front-loaded and concise. Every word adds value; no fluff or repetition.

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

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

For a simple one-parameter read tool with strong annotations and an output schema, the description covers purpose, id semantics, and response content. It could mention when not to use it, but given the simplicity and context from siblings, it is nearly complete.

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

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

Only one parameter 'id' exists. The schema defines it as number with an example, and the description adds that it is the 'numeric id' for a performer. This is minimal but sufficient for a single, self-explanatory parameter. Schema coverage is 0% but the description provides contextual meaning.

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

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

The description uses a specific verb 'Fetch' with resource 'full SeatGeek performer profile' and method 'by numeric id', listing contents (bio, images, taxonomies, stats, related performers). This clearly distinguishes it from sibling tools like performer_by_slug (which uses slug) and performers (which lists).

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 'by numeric id' implies the tool is appropriate when you have a numeric performer identifier, contrasting with performer_by_slug. However, it does not explicitly name alternatives or provide exclusion criteria, so some inference is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds minimal behavioral context beyond purpose, like the fact that it returns the same detail as the performer tool, but does not disclose error behavior or edge cases.

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

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

The description is a single, front-loaded sentence. It starts with the action and resource, then clarifies the input type and output equivalence, with 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?

For a simple one-parameter lookup tool with an output schema, the description sufficiently covers the purpose, input format, and relationship to a sibling tool. It does not need to explain return values because the output schema exists.

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 no description for 'slug' (0% coverage), but the description compensates by explaining it as a 'URL slug' with an explicit example ('taylor-swift'), adding meaning beyond the bare type definition.

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

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

The description clearly states the tool's action: 'Look up a SeatGeek performer profile by URL slug'. It distinguishes from the sibling 'performer' tool by noting it returns the same detail, making the specific lookup-by-slug purpose clear.

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 when you have a URL slug, as shown by the example 'taylor-swift'. However, it does not explicitly state when to prefer this over the 'performer' or 'performers' tools, nor does it provide exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds context about return content (profiles with images, genres, upcoming event counts) and the search-oriented nature, but it doesn't disclose pagination behavior or any potential quirks. This is adequate but not rich, aligning with a score of 3.

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

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

The description is a single sentence that front-loads the verb 'Search' and immediately specifies the resource and search dimensions. Every phrase adds value (scope 'artists, teams, comedians', search keys 'name or genre', return content), with no filler or redundancy.

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

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

The tool has five optional parameters, a full schema, and an output schema, so the description doesn't need to enumerate return details. It covers the primary use case (search by name/genre) and mentions return content. However, it omits the 'slug' search capability and pagination, which are present in the schema, leaving a small gap in completeness.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's phrase 'by name or genre' loosely maps to 'q' and 'taxonomies.name', but it doesn't add meaningful detail beyond the schema. Given the high coverage, the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search SeatGeek performers (artists, teams, comedians) by name or genre; returns performer profiles with images, genres, and upcoming event counts.' It uses a specific verb ('Search'), identifies the resource ('SeatGeek performers'), and distinguishes itself from sibling tools like 'performer' or 'performer_by_slug' by emphasizing multi-result search.

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

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

The description provides clear context on when to use the tool (searching for performers by name or genre), but it does not explicitly mention alternatives or exclusions. For example, it doesn't indicate that 'performer_by_slug' is more appropriate for exact slug lookups. Thus, it earns a 4 for clear context without explicit exclusionary 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 are all false, so the description carries the full burden. It discloses the claim_token flow (filing without an account returns a token; pass it back to read status), rate limiting ('5 per identifier per day'), cost/free status, and the instruction to avoid pasting end-user prompts. No contradiction exists, and it adds substantial context beyond the annotations.

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

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

The description is long but every sentence earns its place: purpose, usage, exclusions, token flow, rate limits, and policy. It front-loads the core action immediately and organizes supporting detail logically. No fluff or repetition.

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

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

With no output schema, the description compensates by explaining the return behavior (claim_token and later status reads). It also covers rate limits, quota impact, and the team's daily digest cadence. For a feedback tool with nested context and multiple enum values, this is complete and actionable.

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

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

Schema coverage is 100%, so baseline is 3 per the rubric. The description adds value by demonstrating the claim_token usage pattern ('pipeworx_feedback({claim_token:"pwfb_…"})') and emphasizing message specificity ('Be specific... 1-2 sentences typical'). This goes beyond the schema's field descriptions, justifying 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature, data_gap, praise) and clearly scopes the tool to Pipeworx tools, differentiating from sibling research/query tools by its feedback 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?

Explicitly states when to use ('Use when a tool returns wrong/stale data... feature/data_gap... praise') and when not to use ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies identification via 'Pipeworx tool names are the ones this connection lists.' This is textbook when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context beyond these: it's a 'self-aggregating signal derived from CF analytics-engine,' contains 'no PII,' and is 'cached 5min-1h depending on window.' This informs the agent about data source, privacy, and freshness.

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

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

The description is well-structured and front-loaded with the core purpose, followed by use cases and technical notes. Each sentence adds value, though it is slightly longer than strictly necessary; the balance of information justifies the length.

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

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

For a tool with one optional parameter and no output schema, the description is highly complete: it specifies what is returned, provides usage rationale, explains the underlying data source, privacy characteristics, and caching behavior. This fully equips an agent to decide when and how to call 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% for the single 'window' parameter, which already includes enum values and a helpful description. The tool description reinforces this by mentioning '24h, 7d, or 30d' but does not add new semantic details 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 what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This is a specific verb+resource combo and distinguishes it from sibling tools like discover_tools by focusing on aggregate usage data rather than a static catalog.

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 three concrete use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It clearly implies when to use this tool, though it does not explicitly name alternative tools or state exclusions.

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

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

With annotations already declaring readOnlyHint and idempotentHint, the description adds valuable behavioral context: it explains the partition filter rules, semantic similarity threshold, the fill check mechanism (realizable_edge_pp ≤ 0 means don't trade), and the shape of the response. No contradictions with annotations.

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

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

The description is long and dense, but front-loaded with the main purpose and mode selection. CAPS labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) aid scanning, though it could be more concise with bullets. Every sentence contains substantive information, so the length is justified.

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

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

No output schema exists, so the description fully describes return values (opportunities[], partition_check, fill_check fields). It covers all modes, describes failure conditions (placeholder fraction >20% returns null), and provides cross-references to sibling tools for related functionality. This is a complete description for a complex tool.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining what each parameter does in detail with examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'). It also clarifies that no args triggers a trending scan, which is not in the schema. This significantly enhances parameter understanding.

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

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

The description opens with a specific verb and resource ('Find arbitrage opportunities on Polymarket') and names the method (monotonicity violations + partition-sum checks). It clearly distinguishes from sibling tools by describing its scope, including multiple invocation modes, though it doesn't explicitly name siblings in this dimension.

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 tells when to use each mode: 'Call with NO args for a trending_scan... pass event for... pass topic for...' It recommends event for specific markets and topic for cross-event scanning, and points to a sibling tool for custom sizing ('For custom sizing use polymarket_fill_risk'). This exceeds the 'when/when-not/alternatives' requirement.

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

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

The annotations already indicate readOnly/openWorld/idempotent; the description adds operational behavior: 1h caching keyed on all knobs, diagnostics for empty segments, '24h-move warning', placeholder-slug filtering, halved Kelly, and slippage handling. This goes far beyond annotation 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 structured and information-dense, with clear sections for model families, knobs, and response fields. Every sentence conveys novel detail; no redundancy. It is at the upper complexity limit but remains parseable.

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 thoroughly defines response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly fractions, liquidity, spread_pp, volume), and trigger conditions for each model family. It covers why segments can be empty via diagnostics.

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

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

Schema covers 100% of parameters, but the description explains parameter interactions that schema descriptions do not: slippage_pp subtracted before ranking, min_kelly not applying to partition arbs (parent-level Kelly=0), and min_partition_leg_kelly applying to per-leg Kelly. This adds essential decision context.

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

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

Description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb-resource-result. It also outlines the three model families and the use case, clearly distinguishing it from sibling tools like polymarket_arbitrage.

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

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

Explicitly states the tool is built for 'what should I bet on today' and avoids paging hundreds of markets. It includes cautions and disclaimers (e.g., Fed bets excluded due to unreliable signal) and guidance on tradeable-edge knobs. It does not name specific alternative tools, but provides clear internal usage context.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial context beyond that: the 60-day snapshot TTL, that history starts from when snapshotting was enabled, that snapshots are written only on cache-miss (so gaps mean no scan), and that decay numbers come from daily closes, not intraday. These are meaningful behavioral insights not inferable from annotations alone.

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

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

The description is efficiently structured: it starts with the core purpose, then defines parameters inline, then details the RESPONSE format with field-level explanations, and ends with LIMITS. Every sentence contributes useful information, and the use of uppercase section labels makes it easy to scan. Though long, the complexity of the tool justifies the detail.

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

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

Given the absence of an output schema, the description takes full responsibility for explaining the return value: tracked[] with detailed per-field semantics, expired[] with lifespan_days, and snapshot_dates[]. It also clarifies data availability limits (TTL, snapshotting start, cache-miss gaps). This is comprehensive and leaves no major gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema already provides clear descriptions for both parameters (lookback with default and clamp, window family). The description repeats this information ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') but does not add new semantic depth beyond what the schema already states. 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 opens with a clear, specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from related tools like polymarket_edges by focusing on the time dimension of edge behavior.

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 clearly communicates when to use this tool: for analyzing edge persistence and decay, with examples like 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternatives or exclusions, but the use case is well implied, and the sibling context (e.g., polymarket_edges) makes the distinction clear.

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

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

The description goes far beyond the read-only/idempotent annotations, detailing internal behavior: walks the order-book ladder, returns top_of_book, VWAP, slippage, shares_filled, verdict, theoretical vs realizable sums, thin_legs, forced_directional_risk, and clamping behavior (size clamp 10–1,000,000). It also discloses the dominant loss mode. No contradiction with annotations; full behavioral 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 long but every sentence earns its place. It is structured with clear mode sections (REQUIRES, SINGLE-MARKET, BASKET) and a closing usage rationale. It front-loads the core purpose and then systematically covers parameters, outputs, and risk. No filler or tautology.

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

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

Given the tool's complexity (two modes, four parameters, rich outputs, no output schema), the description is remarkably complete. It explains return fields for both modes, parameter behavior, edge cases (thin books, partial fills), and the practical context of use. The absence of an output schema is fully compensated by the detailed return-value listing.

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?

Even though schema descriptions cover 100% of parameters, the tool description adds crucial context: single-market vs basket interpretation of `side` and `size_usd`, default values, and mode determination rules (auto side from partition sum). It explains that in basket mode `size_usd` means settlement notional shares per leg, which is not in the schema. This significantly deepens parameter understanding beyond schema.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly frames its role relative to sibling tools like polymarket_arbitrage and polymarket_edges. This is a precise, unambiguous purpose statement.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the failure mode (partial basket fills converting arb into unhedged directional position) and why the tool is needed. This is model clarity for when to use vs. alternatives.

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

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

Even though annotations already mark this as read-only and non-destructive, the description adds substantial behavioral detail: it explains the meaning of compatibility warnings, temporal alignment (aligned:false means spreads are meaningless), skipped_cross_type/subtype counters, and the fact that the tool actively reports when bet shapes are non-equivalent. It also discloses the real-world limitation that many macro shortcuts return warnings today. This goes far beyond the annotation safety profile.

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 rigorously structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence conveys a distinct, useful piece of information—mode selection, output format, safety semantics, and interpretability of warning fields. The initial sentence immediately establishes purpose, and the dense content is justified by the tool's complexity. No redundant or filler sentences.

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

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

Given the absence of an output schema, the description excellently covers the response structure (leg-by-leg prices, spread array, top_spreads_pp), the meaning of each field, edge-case behavior (non-equivalent bet shapes, mismatched temporal alignment), and counters that explain skipped comparisons. It also provides examples of parameter values in the schema, and the description alone gives enough for an agent to understand what the tool returns and why. This is a thoroughly complete description for a complex tool.

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

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

With 100% schema coverage, each parameter is already described in the schema (e.g., topic lists valid values, ticker/slug describe overrides). The description reinforces the two-mode interaction (topic vs explicit) and clarifies that tickers override the mapped side, but it does not add materially new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the exact function (calculating inter-venue spread), the two venues, and the distinguishing caveat about bet-shape equivalence. The two operation modes (topic shortcuts vs explicit tickers) are clearly enumerated, setting it apart from sibling tools like polymarket_arbitrage which focus on single-venue arb.

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 use context: when you want a cross-venue comparison for a known macro topic, use the pre-mapped shortcuts; for custom pairings, use explicit tickers. It also warns that most pre-mapped topics currently return compatibility_warning, implying caution. However, it does not explicitly name alternative tools for cases where this tool is unsuitable, such as direct order-book arbitrage tools. Thus it has clear context but lacks explicit when-not-to-use comparisons with siblings.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by explaining the list-all behavior when key is omitted, scoping by user identifier, and the intended purpose of avoiding re-derivation. 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 three concise sentences. Each sentence adds essential information: action, use case, and scoping/pairing. No wasted words or repetition of schema details.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers behavior (retrieve or list), scoping, and relationship to related tools. It leaves no important 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 for the single 'key' parameter is 100%, with a description. The tool description adds further meaning by explicitly explaining the omit-to-list-all behavior and the role of the key in retrieving previously saved values.

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

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

The description clearly states the tool retrieves values saved via 'remember' and can list all saved keys by omitting the key argument. It distinguishes itself from sibling tools by naming the complementary tools 'remember' and 'forget'.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and notes the pairing with 'remember' and 'forget'. It lacks an explicit when-not-to-use clause, but the guidance is clear and actionable.

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 directly contradicts annotations: readOnlyHint=true and idempotentHint=true, yet mark_read:true mutates the feed state, making the operation non-idempotent. This is a severe inconsistency that misleads the agent about side effects.

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 tightly-written sentences: purpose, response shape, filtering/mutation, and polling note. No redundancy; front-loaded with the core action.

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

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

Given the tool’s 5 parameters and the absence of an output schema, the description covers return content, filter options, mutation behavior, and an alternative endpoint. This is a well-rounded description that would let an agent invoke it correctly, except for the safety contradiction.

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 covers all 5 parameters, and the description adds meaningful context for type, since, and mark_read, especially the effect on subsequent calls. The baseline is 3, but the extra behavioral context for mark_read and filter usage raises it to 4.

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

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

The description clearly identifies the tool as pulling fired events from a subscription feed, with filters and return contents. It uses specific verbs and distinguishes itself by describing the evaluator's persisted feed, which is unique among 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?

It states that polls work fine and provides an HTTP alternative, giving context for when to use this tool. However, it does not explicitly exclude alternatives among the sibling tools, so it stops short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: source selection order, rate-limit fallback, PatentsView API sunset causing soft-fail, and that it returns structured changes grouped by source. This exceeds what annotations alone convey.

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

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

Description is long but densely informative. It uses front-loaded examples and then packs in source behavior, since syntax, return shape, and alternative. No filler, but some might find it slightly dense. Each sentence carries needed detail, so it earns a 4.

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

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

Given the tool's multi-source complexity and lack of output schema, the description fully covers return values (changes[], total_changes, citation URIs), fallback behavior, data source specifics, and an alternative. It is complete enough for an agent to understand the tool's capabilities and limitations without external docs.

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

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

Schema coverage is 100% so baseline is 3. Description adds extra meaning by showing acceptable `since` formats with examples and explaining that it applies to filings/news/patents windows. It also clarifies `value` accepts ticker or CIK, matching schema but reinforcing usage. Not fully compensating beyond schema, but enriches understanding enough for 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?

Description opens with concrete user intents ('What's new with X') then explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and contrasts with entity_profile, clearly distinguishing 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?

Provides explicit usage context: it fans out to multiple sources, explains fallback logic (GDELT preferred, GNews when rate-limited or 5xx), and gives a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This clearly indicates when to use this tool vs. something else.

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: it ranks results, requires a seed, and optional filters narrow the result. It does not contradict the readOnlyHint/idempotentHint annotations, and provides a clear safety profile.

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 purpose, followed by a crucial constraint and a brief filter list. 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 read-only tool with no required schema params, an output schema, and strong annotations, the description covers the core usage (seed-based recommendations) and limitation (not anonymous feed). The 'geoip' mismatch is a minor gap in an otherwise complete picture.

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 provides 100% coverage, so baseline is 3. The description adds useful grouping of seeds vs filters and the seed requirement, but it mentions a 'geoip' filter not present in the schema and uses 'datetime_utc' instead of the schema's 'datetime_utc.gte', introducing minor ambiguity.

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 action ('Get ranked SeatGeek event recommendations') and a clear mechanism ('SIMILAR TO a seed you supply'). It distinguishes itself from sibling tools like events by focusing on similarity to a seed rather than general listing/filtering.

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

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

It explicitly requires at least one seed and excludes an anonymous personalized feed use case. It does not explicitly name alternative tools for browsing, but the context is clear that this is for similarity-based recommendations.

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 valuable behavioral context beyond the annotations: it explains that memory is scoped by identifier, and discloses persistence rules (persistent for authenticated users, 24 hours for anonymous sessions). Annotations already cover read-only, idempotence, and destructiveness, so no conflict exists. Minor aspects like overwrite behavior are not described, but idempotentHint mitigates that gap.

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 five sentences, but every sentence earns its place: purpose, when to use, storage model, persistence, and related tools. It is front-loaded with a clear action verb and avoids fluff. Slightly longer than strictly necessary, but highly informative and well-structured.

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

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

The tool is simple, has no output schema, and only two parameters. The description covers all essentials: what it does, when to use it, how data is stored, how long it persists, and how it relates to recall and forget. This is sufficient for an agent to invoke it correctly with no missing operational details.

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 a baseline of 3 applies. The description reinforces the key-value relationship and gives usage examples, but these largely overlap with the schema's own examples. It does not add new constraints or deeper semantic meaning beyond what the schema already provides.

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

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

The description uses the specific verb 'Save' with a clear resource ('data the agent will need to reuse later') and explicitly differentiates from sibling tools by mentioning recall and forget. It provides concrete examples (resolved ticker, target address, user preference) that make the tool's function unmistakable.

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

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

The description explicitly states when to use the tool ('Use when you discover something worth carrying forward') and gives practical examples. It also names alternatives (recall and forget) for related actions, providing clear usage context without ambiguity.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description goes well beyond these by explaining internal cascading lookups, graceful degradation (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and the explicit reporting of unresolved identifiers. This provides rich behavioral context that annotations alone do not convey.

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

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

The description is front-loaded with user query examples, immediately clarifying the tool's purpose. It is densely packed with valuable information, but the length is justified by the complexity of the tool. It could be slightly more concise by grouping some details, but overall it is well-structured and each sentence adds necessary context.

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

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

Given the tool has 2 parameters, no output schema, and moderate complexity, the description is exceptionally complete. It covers input formats, internal behavior, graceful degradation, what identifiers are returned and how they are labelled, and the handling of unresolved items. An agent has all the information needed to use the tool correctly and understand the output.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. For the 'type' parameter, it explains what each type returns (e.g., company resolves to CIK, LEI, FIGI with source labels). For 'value', it lists accepted input formats (ticker, CIK, ISIN, name) and gives concrete examples like 'AAPL' and 'ozempic'. This adds substantial value beyond the schema's brief descriptions.

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

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

The description clearly states the core purpose: resolving a user-spoken name to canonical/official identifiers. It provides specific verb-resource pairs ('resolve a user-spoken NAME to the canonical/official identifiers') and distinguishes from siblings by positioning itself as the first step when an ID is needed, with detailed coverage of supported entity types (company, drug) and their characteristics.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It also notes that the tool replaces 2-3 manual lookups, reinforcing its utility. However, it does not explicitly mention when NOT to use it or compare against closely related siblings like entity_profile, which slightly reduces the score.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds context: internally calls ai_visibility_check, ranks results, and returns score/confidence/signal density. No contradiction with annotations.

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

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

Three focused sentences, front-loaded with purpose. Every sentence earns its place; no fluff or repetition of schema/annotations.

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 4 params, 1 required, and no output schema, description provides return format and use case. Schema covers parameter details; description could mention models/_apiKey/context but not necessary for selection.

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%, including entity count (2-8) and first-as-subject semantics. Description rephrases this but adds no additional parameter details beyond schema.

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

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

Clear verb+resource: 'Compare AI visibility across multiple entities side-by-side.' Distinguishes from sibling ai_visibility_check by explicitly stating it probes multiple entities, ranks by score, and surfaces most/least recognized.

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

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

Provides clear use case: 'Useful for competitive AI-marketing audits' with example query. Implies ai_visibility_check is for single-entity checks, but no explicit when-not-to-use or alternatives like compare_entities.

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

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

Annotations already mark it readOnly and idempotent. The description adds critical behavioral details: it fans out across two external services, may take 5-30s on first bundlephobia measurement, degrades gracefully with sources_failed listing timeouts, and explicitly enumerates the returned summary block fields. This goes well beyond the safe-read 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 dense but each sentence adds value: composite purpose, usage trigger, return fields, ecosystem scope, and failure behavior. It is longer than typical but justified for a multi-source tool. Slight run-on structure prevents a 5.

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 compensates by listing the exact return fields (summary block, advisory detail, links, alternative versions), the timing caveat, and the graceful degradation behavior. It also clarifies version defaulting and ecosystem limitations, making the tool's behavior fully predictable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little about parameters beyond what the schema states — it mentions 'specific version to check' and 'npm package name' but those are already in the schema. No extra semantic information is provided.

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

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

The description clearly states it is a composite check for answering 'should I add this npm package', explicitly naming data sources (deps.dev and bundlephobia) and the exact question types it addresses. This distinguishes it from sibling tools like scan_competitor_ai_presence and deep_research.

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

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

It provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives an exclusion: NPM ecosystem only in v1, and directs non-NPM ecosystems to deps.dev directly, which is an alternative path.

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

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

The description discloses concrete behavioral details beyond the annotations: it uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', imposes a '200K chars' cap with truncation flagging, and includes character offsets for verbatim quote verification. These are non-obvious behaviors that help the agent anticipate results.

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

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

The description is well-structured and front-loaded: it opens with the core function, then the input/output contract, then usage scenarios, and finally technical details. Each sentence adds unique value with no filler; it is dense but immediately useful.

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 return format (top-N passages with character offsets and similarity scores). It also covers limitations (truncation cap), algorithmic behavior, and integration with a sibling tool, making the description self-sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for 'text' and 'query' by giving examples like 'a SEC 10-K body' and 'natural-language query' with sample queries. It does not add extra detail for 'limit', but the schema already describes it well; hence a 4 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 the tool's function clearly: 'Semantic search INSIDE a fetched record' and specifies the inputs (text, natural-language query) and outputs (top-N passages with offsets and similarity scores). It distinguishes from siblings by emphasizing the 'INSIDE a fetched record' scope and explicitly 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?

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. It also names a complementary tool (ask_pipeworx_grounded) and describes the workflow, which serves as an alternative approach.

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 operational detail beyond the annotations: auth requirements, SMS 10/day cap, phone verification, webhook auto-disable after 10 consecutive failures, and the always-on feed. These complement the annotations (readOnlyHint=false, idempotentHint=true) 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 long but well-organized: purpose first, then subscription types, then delivery channels. Every sentence carries useful information, and the structure makes it scannable despite density. Slightly heavy but not wasteful.

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

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

For a complex tool with nested objects, enums, and no output schema, the description fully captures the essential context: return value, auth prerequisites, all supported types with examples, and delivery behavior. It also cross-references recent_alerts and the registry URL, making it self-sufficient for the 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?

Although the schema already provides comprehensive descriptions for all parameters (100% coverage), the description goes further with concrete examples (items:['5.02'], topic:'fed', series_id:'UNRATE') and clarifies nested delivery constraints like SMS needing a verified phone. This adds practical 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 a specific verb 'Create' with the resource 'proactive monitoring subscription to a live-data event stream' and states the return value (subscription id). It clearly distinguishes from sibling tools like list_subscriptions by focusing on subscription creation.

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 clearly states the required Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions, providing an exclusion. It also lists supported subscription types with concrete examples, giving strong context for when to use it. However, it does not explicitly name alternative tools like recent_alerts for consuming the feed, though it references them.

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

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

The description discloses the return format in detail: 'category-bucketed example questions (company financials, drugs & clinical trials, economics, real estate, prediction markets, weather, government & patents, science & academia, news) — each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' This goes beyond the readOnly/idempotent annotations by explaining what the output contains, and it adds context about the live catalog as the source.

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

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

The description is longer than average, but every part serves a purpose: example queries, output structure, usage modes, and when-to-use advice. It is front-loaded with intuitive queries and then logically structured. Slight verbosity is justified by the tool's onboarding role.

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 one optional parameter and no output schema, the description fully covers how to use it, what it returns, and when to prefer it. It also connects to the broader tool ecosystem by mentioning meta-tools like ask_pipeworx, entity_profile, and compare_entities, making it self-sufficient for an onboarding agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by showing example usages for 'topic' ('finance', 'pharma', 'betting') and explaining the difference between omitting it (full spread) and using it (focused). This clarifies the parameter's purpose beyond the schema's simple enum list.

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 what the tool does: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It uses a specific verb ('Returns') and resource ('example questions'), and it distinguishes itself from siblings by being the 'FIRST' step to learn what Pipeworx can do.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with no arguments for a full spread or pass 'topic' to focus, which covers the when and how to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that it returns all taxonomies and includes hierarchy information, which provides useful context about the response scope and structure beyond what annotations convey. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then adds relevant detail and purpose. Every word earns its place, with no fluff.

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

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

Given zero parameters and the presence of an output schema, the description is complete: it states what the tool returns (IDs and hierarchy) and the use case. The complexity is low, and the description covers the necessary context for an agent to decide when to invoke it.

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

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

The tool has zero parameters, so there are no parameter semantics to describe. The description doesn't need to compensate for missing schema information, and the existing schema is fully covered (100% coverage). Baseline is 4 for no params.

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

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

The description clearly states the action ('List all SeatGeek event taxonomies'), specifies the resource (taxonomies), and includes key details such as IDs and parent/child hierarchy. It also provides a concrete use case ('useful for filtering events by category'), distinguishing it from sibling tools like 'events' or 'performers'.

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 identifies when to use the tool: when filtering events by category. It provides clear context but does not explicitly mention alternatives or when not to use it. The guidance is sufficient for an agent to understand its purpose relative to other tools.

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

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

The description discloses that the row is deactivated rather than deleted, and that historical events remain available via recent_alerts. This adds meaningful behavior beyond the annotations, which only indicate non-destructive and 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?

Two sentences, front-loaded with the action, and every sentence adds new information. No redundancy or filler.

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

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

For a simple one-parameter tool with no output schema and strong annotations, the description covers the essential behavior: what it does, ownership, and the non-destructive deactivation. It is fully sufficient for an agent to use it correctly.

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

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

The schema already provides 100% coverage with a clear description ('Subscription id (uuid) returned by subscribe'). The description only restates 'by id' without adding further parameter-level detail, 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?

The description opens with 'Cancel a subscription by id,' using a specific verb (cancel) and resource (subscription). This clearly distinguishes the tool 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?

It states the core usage context (canceling your own subscriptions) and clarifies ownership enforcement, which guides when to use it. It does not explicitly name alternatives, but the context is clear enough given 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 goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by explaining the exact behavior for each verdict class, especially the critical distinction between could_not_verify (check did not happen) and unsupported (no source exists). It also discloses that returns include citations and reasoning, and notes error structure for could_not_verify. This is rich contextual disclosure not inferable from structured fields.

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 extremely information-dense, with a logical flow: example phrasings, primary use case, execution paths, return structure, caller warnings, and efficiency rationale. Each sentence contributes meaningful content; no filler. It could be slightly more compact by omitting the exhaustive example list, but the structure is clear and front-loaded with the most critical usage directive.

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

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

Given the tool's complexity (two paths, six verdicts, error handling, citations) and the absence of an output schema, the description covers all essential aspects: what it returns, how verdicts are defined, how to interpret ambiguous outcomes, and why it exists (replaces multiple calls). No significant gaps are apparent; the description is sufficient for an agent to invoke and interpret results correctly.

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

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

Though the schema already has full descriptions for both parameters (100% coverage), the description adds important semantic context: it explains how tolerance_pct overrides the claim's implied tolerance, gives a specific use case (1-2 for hallucination detection), and clarifies the default cap of 5. This adds value beyond the schema's basic descriptions.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with a specific verb ("verify") and resource ("factual claims against authoritative sources"). It distinguishes itself from sibling tools by explicitly describing the two execution paths (SEC EDGAR fast path for company-financial claims and grounded pipeline for all others), and states it replaces 4-6 sequential calls, making its unique role evident.

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 explicitly when to use the tool: "Use whenever the agent needs to check whether something a user said is factually correct." It also clarifies the scope (any factual claim) and mentions the efficiency benefit over sequential calls. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of the highest bar.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds field-level detail (address, city, etc.) but does not add behavioral context beyond what annotations provide, such as pagination, rate limits, or response-specific caveats.

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

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

The description is a single, front-loaded sentence with no fluff. It efficiently states purpose, scope, and key response fields, earning every word.

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 one-parameter tool with a rich output schema and safety annotations, the description is mostly complete. It lacks explicit mention that 'venues' is the plural/list alternative, but the singular focus is clear. Overall sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 0% for the 'id' parameter, and the description only says 'numeric id', which is redundant with the schema's type: number and example. It does not explain what the id represents (e.g., SeatGeek venue id), nor does it add meaningful semantics beyond the schema.

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

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

The description clearly states the verb (Fetch), resource (full SeatGeek venue record), and method (by numeric id). It distinguishes from the sibling tool 'venues' by specifying a single-record lookup with full detail.

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 use for retrieving a venue by its numeric id, but does not explicitly state when to use this tool over alternatives like 'venues' or contrast with list operations. No exclusions or alternative tool mentions are provided, so usage guidance is only implicit.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that results include address, capacity, and geolocation, but this is likely covered by the output schema. No additional behavior like pagination details or rate limits is disclosed.

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

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

A single, efficient sentence that is front-loaded with the action and resource. No filler or redundant phrasing. Clearly communicates the tool's purpose and key output.

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 simple with 100% schema coverage and an output schema, so the description is largely sufficient. However, it doesn't explicitly differentiate from the sibling 'venue' tool, which could lead to confusion. Otherwise, it's complete for a search/read 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 description coverage is 100%, so all 7 parameters are already described in the schema. The description just lists some of these parameters (name, city, state, country, postal code) without adding extra meaning beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the tool's function: searching SeatGeek venues by multiple criteria. It specifies the verb 'Search', the resource 'venues', and the output (details including address, capacity, geolocation). The plural 'venues' naturally distinguishes it from the sibling 'venue' tool.

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 finding venues by location/name but doesn't explicitly discuss when to use this over the singular 'venue' tool or other search alternatives. No exclusions or alternative instructions are provided.

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