Ebi Ols

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

The description discloses important behavior beyond annotations: it makes external API calls to Anthropic when a key is supplied, explains that the user pays Anthropic directly for those calls, and describes the exact return structure (per-model score, confidence, signals, raw_response, combined view). The openWorldHint and readOnlyHint are consistent with 'probing' LLMs, with no contradictions.

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

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

The description is compact but information-dense: three sentences cover purpose, default behavior, cost, return shape, and use cases. Every sentence adds value, and the most critical information (what it does) is front-loaded.

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

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

Despite no output schema, the description fully specifies return values (per-model {score, confidence, signals, raw_response} + combined view). It also covers prerequisites (_apiKey for Anthropic), defaults, and representative use cases. This is complete for a tool of moderate 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 baseline is 3. The description adds meaningful context for the '_apiKey' parameter (BYO key, direct payment to Anthropic) and notes the default model, enhancing comprehension beyond the schema alone. Also clarifies how 'models' interacts with '_apiKey'.

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 ('Probe') and resource ('LLMs'), and clearly states the tool's function: scoring visibility (0-100) per model. It distinguishes itself from sibling tools by focusing on LLM knowledge probing rather than searching, chatting, or market data.

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 names use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies cost implications (free default vs BYO Anthropic key). Does not explicitly contrast with sibling tools like compare_entities or scan_competitor_ai_presence, but context is clear enough for a typical agent.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive hints. The description adds behavioral context such as 'one fast call', 'works on every tier', the routing mechanism across many tools, and the return of stable pipeworx:// citation URIs. This goes beyond the annotations without contradicting them.

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

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

The description is longer than ideal but well-structured and front-loaded with the key directive 'PREFER OVER WEB SEARCH'. The varied examples and explicit alternative guidance justify the length, though some redundancy in phrases like 'current or historical data' could be trimmed.

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, the description covers purpose, usage, examples, alternatives, return format (structured answer with citations), and performance characteristics. With no output schema, it adequately explains what the user will receive, making it complete for its scope.

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

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

All six parameters are documented in the input schema with 100% coverage, including the required 'question' field and its aliases. The description does not add parameter-level semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly states that the tool routes questions to the right one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by calling itself the default entry point and explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It explicitly instructs to prefer this tool over web search for factual questions, lists trigger phrases and examples, and explains when to step up to ask_pipeworx_grounded or deep_research. This provides clear when-to-use and when-not-to-use guidance, including named alternatives.

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

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

The description adds substantial behavioral context beyond the annotations, including that candidate routing improvements are enabled live under test, the last candidate was retired on a specific date, and results are compared against the stable router. It also clarifies that the tool currently behaves exactly like ask_pipeworx, which is critical for an experimental variant. The annotations (read-only, open-world, idempotent, non-destructive) are consistent with this description, with no contradiction.

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

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

The description is somewhat long but every sentence carries essential information about the beta status, current state, usage, and behavior. It is front-loaded with the core purpose ('Beta version of ask_pipeworx') and avoids superfluous detail. The length is justified given the complexity of explaining a live-experiment routing variant.

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

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

Given the complexity of a beta router with live candidate testing, the description is remarkably complete. It covers the current state (no active candidate), behavior (identical to stable), usage instructions, comparison with the stable router, and explicitly states it is a full working router. The absence of an output schema is mitigated by noting 'same response shape', which is sufficient given the reference to ask_pipeworx.

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 100% of the parameters, including descriptions for question and its aliases. The description adds that the tool uses 'the same arguments as ask_pipeworx', which reinforces consistency but does not provide additional semantic detail beyond the schema. Since the schema already documents the aliases and the question field, the description does not need to compensate, resulting in the baseline score.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape as the stable version. It explicitly distinguishes itself as the experimental edge, which differentiates it from the stable ask_pipeworx sibling. The verb 'ask' and resource 'Pipeworx' make the purpose unambiguous.

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

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

The description states exactly when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate, so it matches the stable version) and clarifies that it is a full working router, not a fallback. This gives explicit usage guidance and implicitly contrasts with the stable 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 and idempotentHint, but the description adds crucial behavior: it extracts answers only from tool result content, returns a verbatim evidence quote, and provides a structured refusal with enumerated refusal_reason values. It also discloses the cost implication. This goes well beyond the annotations without contradicting them.

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

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

The description is compact yet information-dense. It front-loads the core purpose, then efficiently covers routing, extraction, return shapes, usage guidance, and cost trade-off. Every sentence 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?

Despite having no output schema, the description explicitly documents both success and refusal return structures, including field names and enum values. It also explains the relationship to a sibling tool and the cost/benefit trade-off. Given the tool's complexity, this is a model of 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 coverage is 100% with all six parameters being aliases for question, each documented. The description adds that the question is routed to 'the right tool' and used to fill arguments, which provides light context. However, it doesn't add meaning beyond what the schema already explains, so 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 opens with a specific, actionable purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from sibling ask_pipeworx by explaining the added grounded extraction step and the explicit refusal behavior. The verb+resource is clear and the scope is well-defined.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and specifies high-stakes examples. It also gives a direct alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off (one extra LLM call). This fully covers usage vs alternatives.

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

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

The annotations already declare readOnly/idempotent/non-destructive, but the description goes far beyond that. It exposes resolver confidence levels and alternatives, parent_event extraction, news fallback fields, safety short-circuits (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation-rule parsing. These details are critical for interpreting results correctly and safely, especially for an agent that might otherwise size bets based on unreliable matches.

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 it is efficiently structured into labeled sections (CLASSIFIERS, FAN-OUT, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded with the primary purpose. Every section provides actionable information for correct tool usage, though some redundancy exists (e.g., re-explaining the closed-market path). It is not concise in word count but is internally organized and information-dense.

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 present, the description carries the full burden of explaining return values, and it does so thoroughly: response shapes for market/analysis/evidence, resolver contract with confidence/alternatives/suggestions, parent_event structure, news fallback fields, and blocking statuses. It also warns about cancellation-rule risk, which is essential for bet sizing. The description gives agents everything needed to use the tool correctly and handle edge cases.

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

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

The schema covers all 3 parameters with detailed descriptions (100% coverage), including the market input variants, the depth enum, and the include_raw payload size trade-off. The description adds contextual fan-out examples and classifier lists, but these do not materially change the meaning of the parameters themselves. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: “Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.” It states the input types (slug/URL/question text), the action (resolve, classify, fan-out, compare), and the output (evidence packet + market-vs-model comparison). Explicit use cases “should I bet on X” and “is there edge in Z” further distinguish it from generic ask/search tools.

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

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

The description clearly states when to use the tool: “Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.” It also provides warnings about blocking statuses and cancellation-rule checks before sizing bets. However, it does not explicitly name alternatives or give when-not-to-use guidance, so it falls short of the top 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 readOnly/idempotent/openWorld, and the description adds substantial behavioral context: specific data pulled (10-K fields, FAERS counts), fiscal year handling, sorting by primary metric, and citation URIs in the response. No contradiction with annotations.

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

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

The description is dense but every sentence adds unique value: trigger phrases, core behavior, data sources, edge-case handling, sorting, citations, and efficiency claim. It front-loads usage triggers and remains structured despite its 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?

Complex tool with two entity types and no output schema, yet the description explains return format (paired data + citation URIs), sorting behavior, fiscal year nuances, and even quantifies efficiency ('replaces 8–15 lookups'). Sufficiently complete for the agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful consequences for the 'type' parameter (company pulls 10-K data, drug pulls FAERS/FDA/trial counts) and clarifies values examples (tickers vs drug names), going beyond the schema's brief enum 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 a specific verb ('compare') and resource ('2–5 companies or drugs') with a distinct side-by-side comparison behavior. It distinguishes from siblings like entity_profile and search by emphasizing parallel comparison versus sequential lookups.

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

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

Provides explicit trigger phrases ('X vs Y', 'which is bigger'), states a clear preference ('ALWAYS PREFER over sequential single-pack lookups'), and specifies data sources for each type. This offers strong guidance on when to use and explicitly excludes the 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 extensive behavioral context beyond annotations, including account requirements, paid tier for 'thorough', latency (15-60s, up to ~90s), gaps[] for unanswered facets, 'never invented' assurance, resolvable citation_uri, semantic excerpting, contradictions[] for deeper depths, and hop field. These traits are not covered by readOnly/idempotent hints.

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

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

The description is long but front-loaded with the account prerequisite and alternative tool guidance. Every sentence delivers value: auth, scope, mechanism, output format, usage caveats, depth semantics, latency, and citation behavior. No filler, logical flow.

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 only 2 parameters and no output schema, the description covers nearly every operational detail: findings packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), behavior on unanswerable facets (gaps[]), contradiction detection, latency, and sibling distinctions. This is complete for invocation.

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

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

Schema coverage is 100% for question and depth, so baseline is 3, but the description significantly enriches semantics: it explains what each depth level does (quick=3 facets, standard=gap recovery+contradictions, thorough=paid leads chase) and clarifies that the question accepts broad/multi-part natural language. This exceeds 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 performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains that it decomposes questions and routes to tools in parallel. It distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

Provides explicit usage context: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and for breaking news 'prefer ask_pipeworx'. Also explains when deeper depths are appropriate, giving clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond that: it returns top-N tools with names, descriptions, and full input schemas with curated examples, and results are ready to call directly without a second schema lookup. This informs the agent about output richness and direct usability, which is not in 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 several sentences but every part adds value: the task, domain list, return characteristics, and usage guidance. It is front-loaded with the core purpose. The domain list is long but serves as a quick reference for applicability. No fluff or repetition, though it could be tightened slightly.

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

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

Despite no output schema, the description fully explains the return value (top-N tools with schemas and examples) and the input behavior (accepts aliases, limit). It also covers when to use it. For a tool-discovery utility with good annotations, this description is complete enough for an agent to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the 'query' as a natural-language description and notes it accepts aliases (also in schema). The description does not add significant extra meaning beyond the schema; it reinforces the query parameter's purpose but doesn't provide new syntax details or examples. Thus, a 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 a specific verb+resource: 'Find tools by describing the data or task.' It enumerates many supported domains, making the scope explicit. It also distinguishes itself by saying 'Call this FIRST when you have many tools available' – differentiating it from sibling tools like search or specific data tools.

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This also implies when NOT to use it (when you need a single answer). No alternative tools are named, 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?

Annotations already declare read-only, idempotent, world-open, and non-destructive properties. The description adds valuable behavioral context: it fans out across multiple sources in parallel, notes the USPTO PatentsView API sunset with soft-fail behavior, and describes the GDELT→GNews fallback chain. 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 longer than typical but every section earns its place: examples for intent matching, a clear 'ALWAYS PREFER' directive, a breakdown of returned data, and input constraints. It is well-structured and front-loaded with the most critical usage guidance, though some trimming of example phrases could improve skimmability.

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

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

There is no output schema, so the description compensates by enumerating return fields (cik, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers edge cases (API sunset, fallbacks, input restrictions) and side effects (one parallel call), making the tool's behavior and outputs fully understandable.

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 already describes both parameters with 100% coverage: type is constrained to 'company', and value is documented as ticker or zero-padded CIK with name unsupported. The description reinforces this with concrete examples ('AAPL', '0000320193') and explicitly points to resolve_entity for names, adding practical clarity 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 identifies the tool as a holistic cross-source profile generator for US public companies, using concrete verbs like 'profile', 'research', and 'brief me'. It distinguishes itself from siblings by explicitly contrasting with 'single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-based 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?

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view'. Also states when not to use it (names not supported) and directs to resolve_entity as an alternative, making usage conditions unambiguous.

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 the tool as destructive and idempotent. The description adds behavioral context about clearing sensitive data and acting on previously stored memories, which goes beyond the annotations without contradiction.

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

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

The description is two concise sentences, with the core action front-loaded and every sentence providing necessary guidance. 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?

For a simple one-parameter delete tool, the description covers purpose, appropriate usage, and relationships to related tools. Annotations handle destructive behavior, and no output schema is needed for a delete 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?

The schema covers the only parameter with 100% coverage, defining key as 'Memory key to delete'. The description adds no meaningful new parameter semantics beyond that, 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 clearly states the tool deletes a previously stored memory by key, using a specific verb and object. It distinguishes itself from sibling tools like remember (store) and recall (retrieve) by naming the action and resource.

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 gives explicit use cases: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with remember and recall, indicating the tool's role in a workflow and differentiating from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail: it fetches a page over the network, extracts specific elements, and returns a text blob. This complements the annotations without contradicting them.

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

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

The description is concise and front-loaded with the primary action. It communicates the core mechanism, output, and use cases in just two sentences plus a brief list, with zero unnecessary words.

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

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

With no output schema, the description effectively explains the return value ('a single text blob ready to drop at site-root/llms.txt'). It also covers the input (any URL), process, and use cases, making it complete for a 2-parameter tool with strong annotations.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema fully documents them. The description adds no additional parameter semantics beyond what the schema provides, earning the baseline score of 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific process (fetches page, extracts metadata) and output format. This is a specific verb+resource+scope, and the unique function distinguishes it from siblings like ai_visibility_check or scan_competitor_ai_presence.

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...'), giving clear context on when to use. It does not explicitly name alternative sibling tools, but the scenarios are sufficient for an agent to decide.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds no further behavioral context such as return format or error behavior. It simply restates the resource type without disclosing additional traits.

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 compact sentence that places the core idea—'ontology metadata by id'—at the front. It is appropriately sized with no unnecessary words.

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

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

For a simple one-parameter read tool with a rich output schema and comprehensive annotations, the description is largely sufficient. However, it does not explicitly state what 'metadata' includes or clarify that the id refers to ontology names, so it leaves some ambiguity.

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

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

The input schema only defines id as a required string with no description. The description compensates by giving concrete examples ('efo', 'mondo', 'go') that clarify the expected id format. This adds value beyond the schema, though it does not enumerate all valid 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 indicates the tool returns ontology metadata for a given id, with examples distinguishing it from list_ontologies (which lists all) and get_term (which retrieves terms within an ontology). It is specific and effectively distinguishes from siblings, though the verb is implied rather than explicit.

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

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

Provides no explicit instructions on when to use this tool versus alternatives. The context implies it is for fetching a single ontology's metadata by id, but no alternatives or exclusions are mentioned. It offers only minimal 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds the invocation constraint of passing exactly one identifier, but it does not disclose additional behavioral aspects such as error handling, return format, or edge cases. It is adequate but not rich.

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 is front-loaded with 'Term details' and provides essential parameter guidance without any wasted words. Every word earns its place.

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

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

Given the presence of an output schema and comprehensive annotations, the description is largely complete for a simple retrieval tool. It clearly explains how to call the tool, though it omits guidance on when to select this tool over related term tools, leaving a minor contextual gap.

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

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

The description adds meaning beyond the schema by clarifying that the three identifiers are mutually exclusive alternatives and that short_form and obo_id require the ontology parameter. The schema only describes iri and obo_id, so the description compensates for the 50% coverage with important usage constraints.

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 'Term details' clearly indicates the tool retrieves information about a term, but it lacks a specific verb and does not differentiate from sibling tools like term_ancestors or term_children. It is clear but without sibling differentiation, matching a score of 4.

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 parameter selection rules (pass either iri, short_form, or obo_id, with the latter two requiring ontology) but gives no guidance on when to use this tool versus alternatives. There is no mention of exclusions or preferred contexts, so the score is low.

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 the safety profile. The description adds useful behavioral context: it returns specific fields, supports pagination (size/page controls), and answers the practical question of discovering searchable ontologies and their short IDs. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core action ('page through every biomedical ontology'), and every clause provides value. The second sentence clarifies the return fields and purpose without redundancy. No fluff or excessive 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 tool's simplicity (2 optional params, output schema exists), the description is complete. It explains what the tool does, the scope (all ontologies in OLS), the fields returned, and the practical use case (finding short IDs). With rich annotations and an output schema, there are no major gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'size/page controls' which maps to the 'page' and 'size' parameters, but does not add any new meaning beyond what the schema already provides (defaults, range). The schema's descriptions are sufficient, so no additional semantics are needed.

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 pages through every biomedical ontology in OLS, naming specific ontologies (GO, EFO, MONDO, etc.) and listing returned fields (id, title, description, term count, version, status). It distinguishes itself from siblings like get_ontology and get_term by explicitly focusing on listing all ontologies rather than fetching a single one.

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

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

The description implies when to use the tool: to browse or enumerate all ontologies and find short IDs. It provides context (OLS4, biomedical ontologies) but does not explicitly name alternatives or exclusions like 'use get_ontology for details of a single ontology.' Thus clear context but no explicit 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope is the caller's subscriptions. This is useful behavioral 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 two concise sentences. The first sentence states what the tool does and describes the return format, while the second provides actionable usage guidance. There is no redundant or extraneous information, making it highly efficient.

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

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

Given the tool's simplicity (one optional parameter, no output schema, comprehensive annotations), the description is nearly complete. It covers the purpose, return fields, and usage context. A minor gap is the lack of any mention of pagination or result ordering, but these are not critical for a list operation. Overall, it provides enough information for an agent to use the tool effectively.

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

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

The only parameter, include_inactive, is fully described in the schema with 'Include cancelled subscriptions in the response (default false).' Since schema coverage is 100%, the description does not need to add much. The description's mention of 'active subscriptions' implicitly supports the parameter, but adds no new semantic detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It also distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reviewing existing subscriptions and finding an id to cancel.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly contrasts with subscribe/unsubscribe, but does not explicitly name alternatives. This is clear context without formal exclusions, so a 4 is appropriate.

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 all annotation hints false, the description carries the burden and does well: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token workflow for tracking resolution, and that the team reads digests daily. It could explicitly state that submitting feedback creates a record, but the token and digest behavior strongly imply persistence. Minor gap but strong overall.

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 given the complexity of use cases, exclusions, and claim_token mechanics. It is front-loaded with the core purpose, then flows logically through use cases, exclusions, token usage, and policies. Slightly verbose 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?

The description covers when to use, when not to, claim_token usage, rate limits, and cost. It does not describe the full return shape (e.g., success/failure responses) beyond the claim_token, and the schema's instruction to pass claim_token 'with no other arguments' is not echoed in the description. However, for a feedback tool with no output schema, it is sufficiently complete to guide invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema: it explains the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...') and advises on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This elevates it above baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the verb (tell/send), and differentiates it from sibling tools by positioning it as the feedback channel for this specific connection, with an explicit exclusion for other MCP servers.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: if the tool came from a different MCP server, file it there instead. This fully satisfies the dimension.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable non-obvious context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This goes beyond the annotations, though it doesn't cover every potential behavior (e.g., failure modes).

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

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

The description is concise and well-structured: a clear opening sentence, a list of use cases, and a final note on data privacy/caching. Every sentence earns its place, and the information is front-loaded with the core purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It specifies what is returned (top tools, top packs, total call volume), the data source, privacy guarantees, caching behavior, and practical use cases—sufficient 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 only parameter (window) has 100% schema description coverage, and the description text adds no new meaning beyond the schema. The schema already explains the default and trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). Thus the description does not enhance parameter 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 function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and identifies the resource, distinguishing it from siblings like discover_tools by focusing on what other agents are calling, not just discovery.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It gives clear context but does not mention when not to use it or alternative 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?

The description discloses thresholds (Jaccard ≥0.30, >3pp, >20% placeholder), the partition filter, the fill check behavior, and the meaning of realizable_edge_pp ≤ 0. This goes well beyond the readOnlyHint and other annotations, adding critical context without contradiction.

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

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

The description is long but densely packed with essential information. It is front-loaded with a clear summary and uses capitalized section labels for readability. Every sentence adds value, and the length is justified by the tool's complexity and multiple modes.

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

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

With no output schema, the description fully covers return values (opportunities[], partition_check, fill check fields) and failure modes (skipped_low_similarity, placeholders). It also explains how to interpret results and when not to act, making it complete for real-world usage.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it provides concrete examples of event slugs and topic seeds, explains the no-args behavior, and clarifies the difference between event and topic modes. This enriches the parameter semantics beyond the schema definitions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools by specifying the mechanism and mentioning its fill-check integration, making the purpose specific and unambiguous.

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

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

Explicit guidance is given for each mode: no args for trending_scan, event for specific market analysis, and topic for cross-event scanning. It also clarifies when to use an alternative (polymarket_fill_risk for custom sizing) and warns not to trade when realizable_edge_pp ≤ 0.

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 and idempotentHint, so the safety profile is known. The description adds substantial behavioral context beyond annotations: response structure with by_segment, diagnostic counters, 1-hour caching keyed on knobs, exclusion of Fed bets with reasoning, and the 24h-move warning. No contradictions with annotations.

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

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

The description is long but densely packed with necessary information for a complex tool. It is front-loaded with purpose and then details response structure and knobs. However, it could be improved with headings or bullet points to increase scannability; it currently reads as a wall of text.

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

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

Given no output schema, the description thoroughly defines the response top-level fields, per-opportunity fields, diagnostics, and caching behavior. It explains why certain segments might be empty and how to interpret warnings. This is complete enough for an agent to understand what to expect and how to act on results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and clarifying the distinction between min_kelly and min_partition_leg_kelly (for partition arbs, parent kelly is 0). It also explains when to adjust slippage_pp, which is not fully captured in the schema.

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

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

The opening sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This gives a specific verb, resource, and scope, and the detailed description of model families and output segments distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description frames usage with 'Built for "what should I bet on today"' and provides concrete guidance on parameter tweaks, such as 'Set to 5000 to drop thin-book opportunities' and 'Bump for very thin partitions.' It doesn't explicitly mention when NOT to use this tool or name alternatives like polymarket_arbitrage, but the context is clear.

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

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

Despite annotations already declaring read-only, open-world, idempotent, and non-destructive behavior, the description adds substantial behavioral context: it uses daily snapshots, has a 60-day TTL, explains gaps in snapshot dates, and clarifies that decay numbers come from daily closes rather than intraday data. This goes well beyond annotations.

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

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

The description is dense but well-structured with clear sections for Args, RESPONSE, and LIMITS. Every sentence provides value, including detailed response field explanations and caveats. It is front-loaded with the primary question the tool answers.

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

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

With no output schema, the description fully explains return values (tracked[], expired[], snapshot_dates[]) and their semantics, including edge_pp_net sign convention, trend categories, and median lifespan. It also covers data depth limits and sampling methodology, making it complete for an AI agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates defaults (days=14, window='1wk') but adds little beyond the schema: 'window (snapshot family)' and 'max 30' correspond to schema details. No new parameter meaning 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 the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical edge persistence rather than current edges.

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

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

The description provides clear context on when to use the tool ('Answers how long has this edge existed and is it shrinking?') and contrasts a fresh wide edge with a 3-week-old one. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full 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 declare readOnlyHint=true and idempotentHint=true; the description adds extensive behavioral detail by stating it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and interprets size_usd differently for buys, sells, and basket mode. It also discloses the risk of partial basket fills and forced_directional_risk, going well beyond safety 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 every sentence is information-dense; the first sentence gives the core purpose, the two modes are clearly delimited by SINGLE-MARKET and BASKET labels, and the closing usage guidance is imperative and actionable. There is 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?

Given the tool's complexity and the absence of an output schema, the description enumerates all key return values (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.) and explains the central risk concept of unhedged positions from partial fills. It falls just short of defining every return field precisely, but covers the essential semantics.

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

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

All four parameters have schema descriptions, but the description adds contextual meaning by linking each parameter to return behavior: side options for both modes, size_usd as max spend vs target proceeds, and basket size as settlement notional. This enriches the schema's terse definitions, though it does not introduce entirely new parameter semantics.

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

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

The first sentence states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' naming a specific action and resource. It distinguishes from siblings by explicitly positioning itself as a pre-trade risk check for polymarket_arbitrage and polymarket_edges, and it clearly describes both single-market and basket modes.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' and explains the rationale: theoretical overround on thin books is not capturable and partial fills create unhedged positions. It also differentiates when to use single-market vs basket mode.

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 well beyond annotations by detailing response behavior: compatibility warnings with two distinct cases, temporal alignment semantics, skipped_cross_type/subtype counters, and the rarity of real spreads. It also clarifies that aligned:false makes spreads meaningless. This is rich behavioral disclosure beyond the read-only/idempotent hints.

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

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

The description is long but every sentence earns its place. It is logically structured: purpose, modes, response fields, safety warnings, and a realistic caveat. The density is appropriate for the tool's complexity, and it is well-organized with clear section cues like 'TWO MODES' and 'SAFETY FIELDS.'

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

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

With no output schema, the description fully explains return values: leg-by-leg prices, matched spread array, compatibility warnings, temporal alignment, and skipped counters. It also covers edge cases and practical limitations, making it complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by framing the parameters into two modes (topic vs explicit pairing) and explaining how explicit tickers override topic-mapped defaults. This clarifies the relationship between parameters beyond what the schema descriptions provide.

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 first sentence clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings by focusing on cross-venue comparison and explicitly notes 'when they aren't equivalent the tool says so,' which separates it from arbitrage tools.

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

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

The description explains two modes (topic shortcuts vs explicit ticker/slug) and provides context on when to use each. It also warns that 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility warnings, giving practical guidance. However, it does not explicitly name alternative sibling tools or state when not to use this tool versus 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?

Annotations already indicate read only, idempotent, and non-destructive. The description adds meaningful behavioral context: the scoping to caller identifier, the behavior of listing all keys when omitted, and that values were previously saved via remember. No contradiction.

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

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

Three concise sentences cover purpose, usage, scoping, and pairing with siblings. Each sentence earns its place; the first sentence immediately states the action and optional mode, and the rest add necessary context without fluff.

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

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

For a simple one-optional-parameter tool with strong annotations, the description fully covers what the tool does, when to use it, who it is scoped to, and how it relates to remember/forget. No output schema is needed given the simple retrieval semantics.

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

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

The schema already documents the 'key' parameter with a clear description and examples. The tool description restates the omit-to-list behavior but does not add new semantic detail beyond the schema, 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 clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It names the sibling tools (remember/forget) and provides concrete use cases (target ticker, address, research notes), distinguishing it from alternatives.

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

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

Explicitly tells when to use: to look up previously saved context without re-deriving it. It also explains pairing with remember (save) and forget (delete), giving clear guidance on alternatives and scope (anonymous IP, BYO key hash, account ID).

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 mentions 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state-changing side effect, while annotations declare readOnlyHint=true and destructiveHint=false. This directly contradicts the read-only annotation, as the tool can modify read state. Per rubric, a contradiction yields a score of 1.

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-loads the purpose, and every sentence contributes: purpose/return shape, filtering/flagging, and polling/alternative endpoint. No waste 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?

Given the tool has no output schema, the description explicitly describes the return payload (source, citation_uri, raw event payload). It covers filtering, state mutation, polling suitability, and an alternative REST endpoint, making the description nearly complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter semantics by explaining type with an example ('sec_8k'), since as ISO timestamp, and the effect of mark_read. It does not cover limit or unread_only, but those are sufficiently described in the schema, so the description still adds value beyond structured data.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb ('Pull') and resource ('your subscription feed'). It distinguishes itself from siblings like recent_changes by mentioning 'alerts the evaluator has written' and 'raw event payload', making the scope unambiguous.

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

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

The description gives clear usage context: it describes filtering by type and since, and explains mark_read behavior for polling workflows. It also mentions an alternative access (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, but does not explicitly compare against sibling tools like list_subscriptions.

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

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

Despite having robust annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: data source fan-out, fallback order (GDELT preferred, GNews on rate limit/5xx), USPTO soft-fail due to PatentsView sunset, and parallel execution. This goes well beyond the structured hints.

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

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

The description is compact yet information-dense. It front-loads with query paraphrases, then methodically covers sources, fallback, parameters, return shape, and alternative tool—every sentence earns its place with no redundancy.

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

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

For a 3-parameter tool with no output schema, the description is remarkably complete: it explains the data sources, fallback behaviors, parameter formats, return structure (changes[] grouped by source + total_changes + citation URIs), and provides an alternative tool reference. No critical context 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%, so the baseline is 3. The description enhances parameter understanding by explaining `since` format variants (ISO vs. relative shorthand), providing examples, and adding a usage recommendation ('Use "30d" or "1m" for typical monitoring'). It also adds examples for `value` (ticker or CIK), which, while present in the schema, is reinforced in context.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months' with specific verbs (e.g., 'What's new', 'latest on', 'updates on') and a defined resource scope (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes itself from sibling tools by emphasizing the parallel fan-out and explicitly contrasting with entity_profile.

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

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

It provides explicit when-to-use context via natural language queries and when-not-to-use guidance by stating 'Use entity_profile instead when you want the static profile... regardless of window.' This directly names an alternative, fulfilling the 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?

Beyond the annotations, the description adds critical behavioral context: storage is scoped by the agent's identifier, authenticated users get persistent memory, and anonymous sessions retain data for only 24 hours. It also explains the key-value structure and how the tool fits into the memory lifecycle, which is not implied by the 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 concise and front-loaded: the first sentence states the purpose, the second gives usage context, and the third covers storage details and sibling relationships. Every sentence earns its place without redundancy or fluff.

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

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

For a simple write-only tool with two string parameters, the description fully covers purpose, usage, persistence behavior, and related tools. No output schema is needed for a memory write, and the details about auth/TTL provide sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%, with both 'key' and 'value' already well-described including examples. The description only repeats the 'key-value pair' concept without adding additional parameter-level meaning, so it meets the baseline but does not exceed it.

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: 'Save data the agent will need to reuse later' with the specific resource being memory. It also distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete,' which sets it apart from other tools.

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

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

It provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples like resolved ticker, target address, user preference, and research subject. It also mentions pairing with recall and forget, clarifying the alternative/complementary tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: identifiers are labeled with their source, unresolved identifiers are explicitly stated rather than omitted, enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, and each call cascades through multiple endpoints. These are value-adding transparency details not present in 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 longer than average but well-structured: it starts with practical example queries, then states the core purpose, then details supported types with sub-details. Each sentence adds useful information. It could be slightly more concise, but the length is justified by the need to describe two entity types and fallback behavior.

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

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

Without an output schema, the description compensates by explaining what is returned (identifiers labeled with source, unresolved list), how failures degrade gracefully, and that it replaces multiple lookups. It covers the key edge cases and gives the agent enough context to use the tool effectively.

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

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

The input schema already provides 100% coverage for both parameters, explaining type enum and value formats with examples. The description adds context about supported entity types but does not add meaning beyond what the schema already specifies. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description explicitly states the action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names specific resources (CIK, ticker, LEI, FIGI, RxCUI) and distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource with clear differentiation.

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

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

The description gives direct guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies input formats for each entity type. However, it does not explicitly mention alternatives or when not to use the tool, though the 'use first' phrasing implies priority. No explicit exclusion like 'if you already have an ID, use entity_profile instead.'

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 reveals that the tool internally calls ai_visibility_check for each entity and then ranks results, which goes beyond the annotations (readOnlyHint, idempotentHint). It also states the output format (ranked list with score, confidence, signal density). This is useful behavioral context not available 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 three sentences with no redundancy. It front-loads the main purpose, gives a concrete use-case example, and describes the output. Every sentence earns its place.

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

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

For a tool with no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density) and the mechanism (probes each entity with ai_visibility_check). It doesn't discuss error handling or rate limits, but given the read-only, idempotent annotations and full schema coverage, it is sufficiently complete for an agent to 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?

The input schema has 100% coverage with detailed descriptions for all four parameters, including the special handling of the first entity in the entities array. The description adds minimal new parameter information beyond what the schema already documents, so it stays at the baseline of 3.

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

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

The description clearly states a specific action: comparing AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. It explicitly differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by focusing on AI visibility ranking.

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

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

The description gives a concrete use case ('competitive AI-marketing audits' with an example question) and implies when to use this tool over single-entity checks. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to choose appropriately.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses behavioral traits such as the composite fan-out across two services, partial failure degradation, a potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. It also lists specific return data fields, providing transparency about what the agent will receive.

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

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

The description is detailed but every sentence serves a purpose: it front-loads the core value proposition, then lists use cases, return fields, ecosystem limitations, and failure behavior. It is organized in a logical flow, and the length is justified by the tool's complexity (composite operation with multiple failure modes).

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 is complex (composite, multiple data sources, partial failures) and there is no output schema, the description compensates by enumerating the exact return fields (summary block, per-advisory detail, links, alternative versions), explaining the timeout behavior, and noting how failures appear. This provides a complete picture for an agent to correctly interpret results.

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

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

The input schema already provides full descriptions for both parameters (100% coverage), so the baseline is 3. The tool description adds minimal extra parameter meaning—it reinforces that package is an npm package and mentions version defaults to latest, but these details are already in the schema. It doesn't significantly enrich parameter 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 tool is a composite check for 'should I add this npm package to my project', naming specific data sources (deps.dev, bundlephobia) and the types of questions it answers (safe/popular/small, cost of adding lodash). It distinguishes itself from siblings by focusing solely on npm dependency evaluation, unlike the other tools which target AI, research, entities, or comparisons.

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 whenever an agent asks is X safe / popular / small' and provides a concrete example. It also states an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to an alternative for non-npm packages. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context by noting the scope ('all ontologies or one'), but does not disclose pagination, rate limits, or return format details.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the essential scope and optional restriction in under 10 words, making every word purposeful.

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

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

Given the presence of an output schema and comprehensive annotations, the description is sufficient for a straightforward search tool. It correctly conveys the global scope and optional ontology restriction, though it lacks deeper context about matching behavior or supported search syntax.

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 high (80%), with only the required 'query' parameter lacking a description. The tool description does not add parameter-level semantics beyond what the schema already provides (e.g., 'or one' reflects the ontology parameter). 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 uses a specific verb ('search') and identifies the resource as 'across all ontologies (or one)', which clearly distinguishes it from targeted tools like get_term or search_within. The phrase 'full-text search' adds specificity about how it operates.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or name sibling tools, leaving the agent to infer usage from the schema alone.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral detail: output includes character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and has a 200K char cap with truncation flagged. This goes far beyond the structured annotations.

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

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

The description is dense but every sentence serves a purpose: definition, use case, pairing, and technical constraints. It is front-loaded with the core purpose and uses formatting (capitalized 'INSIDE', example accents) to aid readability without waste.

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

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

Given no output schema, the description explains return values (passages with offsets and similarity scores). It covers input constraints, pairing with sibling tools, and technical behavior. The agent receives all necessary context to decide when and how to invoke this tool.

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

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

Schema descriptions cover all 3 parameters (100% coverage), so baseline is 3. The description adds extra semantics: clarifies that 'text' is pre-fetched content, provides query examples, and explains the limit's range and default (1-20, default 5). This supplements the schema meaningfully, warranting 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 begins with 'Semantic search INSIDE a fetched record', clearly stating the verb (search) and resource (a fetched record). It distinguishes itself from sibling tools by emphasizing 'inside a fetched record' and pairing with ask_pipeworx_grounded, which clarifies its unique scope.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also describes the workflow with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document', giving clear guidance on how it fits among alternatives.

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

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

Annotations indicate a non-read-only, non-destructive, idempotent operation, but the description adds significant behavioral detail: OAuth account requirements, phone verification, 10/day SMS cap, webhook signing secret returned once, auto-disable after 10 consecutive failures, and always-on feed behavior. This goes well beyond the structured annotations.

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

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

The description is dense but well-organized and front-loaded with the core action and return value. Every sentence provides necessary information—auth, type examples, delivery channels, and edge-case constraints—without 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 high complexity (5 enum types, nested delivery object, no output schema), the description is remarkably complete. It covers required auth, per-type parameters, delivery options, verification requirements, failure behavior, and retrieval alternatives, enabling correct invocation.

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

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

Schema coverage is 100% and already contains examples, but the description adds practical meaning beyond field names—e.g., sec_8k items 5.02 means officer change, polymarket_edge topic:'fed', fred_series series_id:'UNRATE', and the requirement that clinical_trial must have sponsor or condition. It also clarifies delivery constraints like verified phone and caps.

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+resource pattern: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning the new subscription id.

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 contextual guidance: proactive monitoring vs pulling via recent_alerts or the registry endpoint, plus OAuth requirements and supported types. It does not explicitly enumerate 'when not to use' or name all sibling alternatives, so it falls just 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 read-only, open-world, idempotent, and non-destructive traits. The description adds behavior beyond that: it returns category-bucketed examples, includes exact tool-call shapes, is based on a live catalog, and supports optional topic focus. No contradiction.

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

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

The description is long but front-loaded with common user questions and then structured explanation. Each part contributes useful information, though the opening question list is somewhat redundant with the title.

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 one optional parameter, no output schema, and rich annotations, the description fully covers what is returned, how to filter, and when to use it. It provides enough detail for an agent to invoke correctly without ambiguity.

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

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

The input schema already fully documents the single optional topic parameter with an enum list and omit behavior. The description adds only rephrased examples, matching the baseline for high 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 returns category-bucketed example questions with the exact tool and argument shape, and positions itself as the onboarding entry point. This distinguishes it from siblings like ask_pipeworx or discover_tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic versus call with no arguments. It does not explicitly name alternative tools to avoid, but provides clear 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?

The annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds the behavioral detail that the result includes the full transitive closure of ancestors, not just immediate parents, which is not evident from the name or schema. It does not discuss edge cases or error handling, but given the strong annotation coverage, this is acceptable.

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

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

The description is extremely concise, consisting of only four words. It is front-loaded and contains no redundant or filler content. However, it may be too terse, missing opportunities to elaborate on usage or parameters, but conciseness itself is well-executed.

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

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

Given the tool's simplicity (two required parameters) and the presence of an output schema (which likely documents return values), the description could be minimal yet sufficient. However, it lacks critical contextual information such as when to use this tool, how the transitive ancestors are computed (e.g., whether self is included), and any domain-specific nuances. The description leaves too much to inference.

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

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

The schema has zero description coverage, so the description must compensate. It only mentions 'a term' without explaining how 'ontology' and 'iri' relate to identifying that term. The parameter names are self-explanatory, and the schema example provides some context, but the description itself fails to add meaningful parameter-level guidance.

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

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

The description clearly states that the tool returns 'transitive ancestors of a term,' which specifies the resource (term) and the action (returning ancestors). It distinguishes itself from sibling tools like 'term_children' by the word 'transitive,' indicating all ancestors rather than just direct parents. However, the verb is implicit and the term 'transitive' might be ambiguous to non-domain experts.

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?

There is no guidance on when to use this tool versus alternatives. The presence of sibling tools like 'term_children' and 'get_term' suggests potential overlap, but the description does not mention these or provide heuristics for choosing this tool. It lacks any context about exploration of ontology hierarchies or relationships.

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 this as read-only, idempotent, and non-destructive. The description adds the behavioral detail that it returns only direct children, not descendants, which is useful. However, it does not disclose behavior for edge cases such as terms with no children or invalid IRIs.

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

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

The description is extremely concise with no filler, but it is under-specified. It reads more like a title or subtitle than a functional description, and its brevity does not compensate for the lack of parameter 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 an output schema and strong annotations, the core behavior is mostly captured by 'Direct children of a term.' However, the lack of any usage context or parameter explanation leaves meaningful gaps, making it only minimally adequate.

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

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

Schema description coverage is 0%, and the description does not explain the 'ontology' and 'iri' parameters. The parameter names are self-explanatory to some degree, but the description adds no additional meaning about formats, examples, or constraints beyond what the schema's example shows.

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 'Direct children of a term' conveys the resource and scope, but it is a noun phrase rather than a clear verb-driven statement. It adds the 'direct' qualifier, which distinguishes it from term_ancestors, but it still largely restates the tool name 'Term Children' without explicitly noting that it returns or lists results.

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

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

No guidance is provided about when to use this tool versus siblings like term_ancestors or get_term. The description does not mention traversal scenarios, prerequisites, or any exclusions, leaving the agent to infer usage from the name alone.

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=false, destructiveHint=false), the description adds crucial behavior: ownership is enforced (only your own subscriptions) and the row is deactivated rather than deleted, making historical events accessible via recent_alerts. This significantly clarifies the 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?

The description is compact (two sentences, three clauses) and front-loaded with the action. Every sentence adds value: action, ownership restriction, and the deactivation/visibility nuance.

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, the description covers the action, the constraint, the side effect, and the relationship to recent_alerts. It is complete and self-contained.

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

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

The schema already fully describes the id parameter (uuid returned by subscribe). The description adds the ownership constraint ('only cancel your own subscriptions'), which is directly relevant to which id values are valid, thus supplementing 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 states the verb ('Cancel') and resource ('subscription') clearly, including the identifier ('by id'). It distinguishes from siblings like subscribe (creating) and list_subscriptions (listing) by specifying the cancellation action.

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 implies when to use the tool (you have a subscription id and want to cancel it) and explicitly mentions recent_alerts as the destination for historical events, but does not directly contrast with subscribe or state when not to use it.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description details behavior that would otherwise be opaque: the verdict taxonomy, the significance of 'could_not_verify' with verification_error, and the distinction between 'unsupported' and 'could_not_verify.' It also notes the pipelining and citation behavior, adding substantial context beyond the structured annotations. No contradictions.

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

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

The description is longer than the average tool, but every section serves a purpose: trigger phrases, usage, path routing, return values, and critical caveats. It is well-organized and front-loaded, though slightly verbose; the 'IMPORTANT for callers' block is essential. A 4 reflects effective structure with a minor 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 no output schema, the description fully compensates by explaining the verdict set, evidence/citation behavior, and the meaning of each failure mode. It covers the tool's complexity (fast path vs. fallback) and gives enough guidance for correct invocation, making it complete for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context about tolerance_pct: how it overrides the wording-implied tolerance, default capping at 5, and suggested use (1–2 for hallucination detection). This goes beyond the schema 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 clearly identifies the tool as a natural-language claim verification tool, listing trigger phrases like 'fact check' and 'verify the claim that.' It distinguishes itself from siblings by describing the SEC EDGAR fast path for company financials and the grounded pipeline fallback for all other claims, making its unique value explicit.

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

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

It explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further guides on internal routing (company-financial vs. other claims) and mentions it replaces 4–6 sequential calls, making the choice over manual alternatives clear.

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