Gdacs

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

The description adds behavior beyond annotations by stating that the default model is free (Workers AI Llama-3.3-70b), that passing _apiKey enables Anthropic probing with direct billing to the user, and that results include per-model and combined views. This supplements the readOnlyHint and idempotentHint 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?

Three sentences cover purpose, default behavior, return structure, and use cases. Information is front-loaded with the core action, and every sentence adds essential context. No redundancy or filler.

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

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

Given no output schema, the description appropriately discloses the return format (per-model score, confidence, signals, raw_response, plus combined view). It also covers use cases and key options. It lacks potential error conditions or rate-limit details, but these are not critical for the tool's basic use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying the default model for the 'models' parameter and clarifying that _apiKey is only needed for Anthropic, plus noting cost implications. These details enhance the schema's descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility on a 0-100 scale. It distinguishes itself from sibling tools like ask_pipeworx (which likely answers questions) and deep_research (which conducts broader research) by focusing on AI visibility scoring.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context on when to use it. It does not explicitly name alternative tools or state when not to use it, but the guidance is sufficient for an agent to select this tool appropriately.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful behavioral context: it routes to thousands of tools, fills arguments, returns structured answers with citation URIs, and claims 'one fast call' and 'works on every tier.' This goes beyond the annotation set, though it doesn't detail potential latency variation or 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 dense yet organized: preference statement, functional summary, query trigger phrases, examples, default-entry guidance, and alternative routing are all present without repetition. Each sentence carries weight, and the most critical decision guidance ('PREFER OVER WEB SEARCH') 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 having no output schema, the description explains the return value ('structured answer with stable pipeworx:// citation URIs') and the breadth of coverage. It also addresses edge cases like breaking news and provides examples spanning finance, health, patents, weather, and crypto. Given the tool's complexity, this is a complete picture for selection and 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 description coverage is 100%, with each parameter labeled as an alias for 'question,' so the baseline is 3. The description adds a few illustrative queries ('current US unemployment rate', 'Apple's latest 10-K') that clarify acceptable input semantics, but it doesn't materially expand on the schema's already-clear natural-language parameter definition.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and states the tool's core action: routes questions to one of 5,743 tools across 1,500 verified sources and returns structured answers with stable pipeworx:// citation URIs. It is sharply distinguished from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, leaving no doubt about which tool to use.

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 the user asks...' with concrete phrases and examples, then states 'START HERE for most questions.' It names exact conditions for stepping up to ask_pipeworx_grounded (hallucination-resistant single answer with verbatim evidence + confidence) and deep_research (broad/multi-part fan-out), as well as a breaking-news caveat.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful behavioral context beyond that: it is a beta/experimental edge, candidate routing changes may be live, no candidate is currently active, and there is no fallback — it is a full working router. This is highly transparent.

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

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

The description is front-loaded with the tool's identity and current behavior, and each sentence contributes useful information. There is minor redundancy between 'Beta version', 'experimental edge', and 'currently matches ask_pipeworx exactly', but overall it is well structured and not bloated.

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 universal router with no output schema, the description covers current behavior, relationship to the stable tool, and what the agent should expect. Referencing the same response shape as ask_pipeworx bridges the missing output schema. It is complete enough for confident selection and 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 description coverage is 100%, with six parameters and all aliases documented. The description says 'same arguments' but adds no parameter-level meaning beyond the schema. Baseline of 3 is appropriate since the schema carries the full burden.

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 beta universal router that behaves identically to ask_pipeworx, with the same 5,743 tools and response shape. It also distinguishes it from the stable router by noting the experimental routing improvements. This is a specific, unambiguous purpose that an agent can act on.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx exactly, which is useful context. It does not explicitly exclude cases or compare against ask_pipeworx_grounded, 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?

Discloses far beyond the annotations: exact success return shape, refusal reasons enum, the guarantee that only tool-result content is used, and the extra LLM call cost. It also clarifies refusal behavior (not_in_source, no_tool_match, etc.) which annotations alone could not convey. No contradiction with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

Every sentence serves a distinct purpose: purpose, routing mechanism, grounding guarantee, return/refusal contract, use-case guidance, trade-off, and alternative. The most important differentiator (hallucination-resistant, grounded answering) appears first. Despite being detailed, 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?

For a tool with no output schema, the description fully covers return values, error/refusal modes, usage conditions, and relationship to the sibling tool. An agent has everything needed to invoke it correctly and interpret its result. The complexity of routing across 5,743 tools and the grounded-extraction behavior is adequately disclosed.

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

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

Schema description coverage is 100%, with every parameter documented as an alias for the natural-language 'question'. The description adds no parameter-level detail, but with complete schema coverage, the baseline of 3 is appropriate. It does not need to compensate for any undocumented fields.

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

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

States a specific, differentiated purpose: a hallucination-resistant answer mode that extracts answers only from fetched tool results and returns explicit refusals when data is insufficient. The phrase 'Same routing as ask_pipeworx' plus the grounded extraction behavior clearly separates it from its sibling. This is far more than a restatement of the name.

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 for quoted, cited, or acted-on answers in high-stakes contexts like financial, legal, medical, or public-statement lookups. It also names the alternative (ask_pipeworx) and gives a concrete preference rule: use the cheaper casual lookup for non-critical questions. No inference is required.

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

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

The description goes far beyond the simple readOnly/non-destructive annotations, disclosing detailed behavioral nuances: the resolver contract with match confidence levels and suggestions, short-circuiting on low-confidence matches, handling of closed/de-indexed markets, wide-spread illiquidity notes, cancellation-rule risk with EV impact, and news fallback fields. It fully prepares the agent for edge cases and safe invocation, with no contradiction to the annotations.

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

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

The description is long but well-organized with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and front-loaded with the core purpose and use cases. Every section contributes critical operational detail, so the length is justified for the tool's complexity, though a more concise summary might improve scannability.

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

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

With no output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence), status codes, safety paths, and resolution-rule risk. It explains both blocking routes for dead markets, parent-event extraction for partitions, and news fallback behavior, making the tool's behavior fully specified for an agent without needing external documentation.

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

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

The schema already describes all three parameters, but the description adds meaning through concrete examples of market inputs, an explanation of the depth parameter's behavior, and a rationale for include_raw (response size tradeoff, when to override the default). This enriches the schema's baseline, making the parameters more actionable.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the tool's scope with input formats (slug, URL, question text) and explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from siblings like validate_claim or ask_pipeworx by focusing on market research with cross-source 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 states 'Use for ...' with three common query types and provides a classifier list plus fan-out examples, which strongly imply when this tool is appropriate. It does not explicitly name sibling tools as alternatives or give 'when not to use' exclusions, but the context is clear enough for an agent to select this tool for bet-specific research queries.

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 beyond the annotations by detailing exactly what data is pulled for each type: company (latest 10-K revenue, net income, cash, long-term debt from SEC EDGAR/XBRL) and drug (FAERS adverse-event counts, FDA approval counts, active trial counts). It also discloses fiscal-year handling, result sorting by primary metric, output format (paired data + pipeworx:// citation URIs), and performance impact (replaces 8–15 lookups).

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 clause earns its place. It front-loads trigger phrases, then explains behavior in a logical flow: what it does, when to prefer it, data specifics per type, sorting, output, and efficiency gain. No filler or repetition.

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

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

For a tool with only two parameters and no output schema, this description is remarkably complete. It covers what the tool does, when to use it, what data each type returns, how results are ordered, and what the output contains (paired data + citation URIs). The performance benefit (replacing 8–15 lookups) adds useful context for agent decision-making.

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

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

Although the schema already covers parameter documentation (100% coverage), the description adds meaning by explaining what each type triggers: "type='company' pulls LATEST 10-K..." and "type='drug' pulls FAERS..." It also gives concrete examples for the values array (["AAPL","MSFT"], ["ozempic","mounjaro"]), which clarifies expected input format beyond the schema's generic descriptions.

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

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

The description opens with concrete trigger phrases ("Compare X and Y", "X vs Y", "head to head") and states the core action: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It clearly distinguishes itself from sequential lookups and sibling tools like entity_profile by emphasizing the comparative, batched nature.

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 provided: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also includes example user intents ("which is bigger / better", "rank these companies") to signal when this tool should be selected, making the usage context unmistakable.

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, openWorld, idempotent), the description discloses important behaviors: account/paid-plan requirements, NOT open-web search, findings packet structure with gaps[] never invented, second-hop gap recovery, contradictions[] for standard/thorough, semantic excerpting, and timing ranges. This is rich and exceeds what annotations convey.

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

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

The description is long but front-loads the critical account requirement and scopes the tool immediately. Some sentences repeat schema content (e.g., depth behavior), but most add unique value such as timing, citations, and excerpts. It is dense yet coherent, with each major section earning 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?

With no output schema, the description carries the burden of explaining return values — and it does: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradiction[], and hop field. It also covers account requirements, alternatives, timing, and failure behavior, making it complete for an agent to call correctly.

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

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

Schema description coverage is 100% and already thoroughly explains both `question` and `depth`, including the difference between standard and thorough. The description adds a bit of nuance ('depth:"thorough" needs a paid plan') and examples, but largely restates schema content, so it meets the baseline without exceeding 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 uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources ... in ONE call.' It explicitly contrasts with open-web search and names sibling tools like ask_pipeworx, making the tool's distinct role clear.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It gives direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also includes account prerequisites and fallback if not signed in.

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 useful behavior: returns top-N tools with names, descriptions, and full schemas, and states 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations and helps set expectations.

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, front-loaded with the purpose, and every sentence earns its place. The second sentence is a long list of domains, but it provides useful specificity for a discovery tool. It remains efficient and readable.

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 moderate complexity and the absence of an output schema, the description compensates well by explaining the return value (top-N tools with schemas and examples) and the primary use case. There are no major gaps for a read-only discovery tool.

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

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

Schema description coverage is 100% and the schema already explains all parameters, including aliases and examples. The description only restates that 'query' is a natural language description and does not add additional meaning beyond what the schema provides, so a baseline middle score 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+resource: 'Find tools by describing the data or task.' It clearly states the tool's function and differentiates it from siblings by establishing itself as the discovery/search entry point, not a data retrieval or analysis tool.

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

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

The description gives clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and explicitly says 'Call this FIRST when you have many tools available.' However, it does not provide explicit when-not-to-use guidance or name alternative tools directly.

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

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

Beyond the read-only/idempotent annotations, the description discloses multi-source fan-out, parallel execution, soft-fail behavior (USPTO sunset), the meaning of empty sections vs bugs, and private-company resolved:false behavior. This adds real behavioral context rather than repeating 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 first sentence is a good front-loaded hook, but the description then becomes a dense, run-on paragraph listing return fields and edge cases. Every sentence is informative for a complex tool, yet the lack of bullet structure makes it hard to scan.

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

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

With no output schema, the description carries full burden for explaining return values, and it does so thoroughly: it lists output fields, source failure signaling, name resolution semantics, and expected-empty cases. The agent has enough to invoke and interpret the call correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful nuance beyond the schema by stating that type values are interchangeable, showing example ticker/CIK/name formats, and explaining SEC EDGAR name resolution. This exceeds baseline but still mostly restates parameter concepts present in the schema.

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

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

The description clearly states it builds a full cross-source profile of a US public company, with concrete user-phrase examples ('Tell me about X', 'brief me on Tesla'). It does not explicitly differentiate from sibling tools like compare_entities or resolve_entity, only from chaining single-pack lookups, so it misses the top bar for sibling 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?

It gives an explicit directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' plus accepted input shapes. It stops short of saying when not to use the tool versus named siblings such as compare_entities, so guidance is strong but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds useful context about return content (metadata, impact estimates, geometry) and the valid event type codes. No contradiction; description complements 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?

Single, concise sentence that fronts the main action (Fetch full detail) and packs in parameters, event types, and return content. No irrelevant information.

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

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

Given the simple tool with 3 params, rich annotations, and output schema, the description covers the essential aspects: what it returns, how to identify the event, and optional episode narrowing. No significant gaps.

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

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

Schema has 0% description coverage, so the description compensates by explaining the purpose of event_type and event_id, listing valid event type values (EQ/TC/FL/VO/DR/WF), and indicating episode_id as an optional narrowing parameter. This adds meaning beyond the schema's bare property names, though episode_id semantics remain somewhat ambiguous.

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

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

The description clearly states the tool fetches full detail for a single GDACS disaster event, identifying required identifiers (event_type, event_id) and optional episode_id. This distinguishes it from sibling 'events' (plural).

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

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

It clearly implies usage for retrieving a single event's details given event_type and event_id, and mentions optional narrowing by episode_id. However, it does not explicitly mention when not to use it or name alternatives, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent safety. The description adds the data source (GDACS) and clarifies the filtering dimensions, which supplements the annotations with useful context. No contradictions.

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

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

A single, information-dense sentence that front-loads the core purpose and then lists filters. No wasted words; every clause adds value.

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

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

With a rich annotation set and output schema present, the description covers the essential behavior and filters. It could mention that all parameters are optional or how results are ordered, but these are minor given the schema and 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?

The description expands event_type codes to full disaster names (earthquake, tropical cyclone, etc.), which the schema does not explain. It also specifies 'ISO' for date formatting and ISO3 for country code, adding meaning beyond the schema's terse descriptions.

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

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

The description states a specific verb ('Search and list') and resource ('GDACS global disaster events') with filtering dimensions. It clearly distinguishes from the singular sibling tool 'event' by emphasizing the list/search nature.

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

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

Provides clear context for when to use the tool: searching and listing events with optional filters. It does not explicitly mention alternatives or exclusions (e.g., 'for single event details, use event'), but the scope is 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 declare destructiveHint and idempotentHint. The description adds context about the resource being memories saved by the agent, and highlights clearing sensitive data. It does not contradict annotations and provides meaningful behavioral context beyond the structured data.

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

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

Two concise sentences. The first delivers the core action, the second gives usage scenarios and related tools. No unnecessary words or repetition.

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

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

For a simple one-parameter delete tool with annotations covering destructiveness and idempotency, the description covers purpose, use cases, and related tools. No output schema exists, so no need to describe return values. The information is sufficient for an 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% with 'key' described as 'Memory key to delete.' The description only says 'by key,' which adds no new information beyond the schema. 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 action: 'Delete a previously stored memory by key.' This uses a specific verb (delete), resource (memory), and method (by key), distinguishing it from sibling tools remember and recall.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, indicating alternatives, but does not explicitly state when not to use the tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a 'single text blob,' giving agents a clear expectation of the result. 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 three sentences, each earning its place: the first states the core purpose, the second outlines the process, and the third lists concrete use cases. Information is front-loaded and concise with no filler.

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

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

Given the tool's simplicity (2 fully-described parameters, strong annotations, straightforward output), the description is complete. It provides enough detail for an agent to select and invoke the tool correctly, including the output format and typical use cases. No additional information is needed.

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

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

The schema already provides 100% description coverage for both parameters (url and max_links). The description adds context about what is extracted (title/description/key links) but does not meaningfully enhance the parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It distinguishes itself from siblings like scan_competitor_ai_presence by emphasizing the generation of the llms.txt file itself, not just analysis.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use the tool, but it does not explicitly name alternative tools 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal context ('current alerts') but does not disclose pagination, filtering behavior, data freshness, or response structure nuances beyond what the output schema provides.

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 only five words, which is concise but under-specified. It is more of a fragment than a complete sentence and omits essential usage context, making it insufficient rather than efficiently concise.

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

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

Despite having optional parameters, an output schema, and good annotations, the description fails to explain the meaning of 'current alerts', how the filters work, or when this tool is appropriate. The minimal context leaves critical gaps for an agent to decide when to use it.

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

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

Schema description coverage is 0%, and the tool description does not mention the parameters 'event_type' or 'alert_level'. The agent receives no information about valid values, defaults, or how these parameters filter the alerts, making it impossible to use them correctly.

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 'Current alerts as GeoJSON' clearly indicates the tool returns current alerts in GeoJSON format, differentiating it from similar tools like 'recent_alerts' or 'events' by format. However, it lacks an explicit verb such as 'Get' or 'List', making it a noun phrase rather than a direct command.

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 no guidance on when to use this tool versus alternatives like 'recent_alerts' or 'events'. There is no mention of scenarios, exclusions, or criteria for preferring GeoJSON output.

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, so the safety profile is clear. The description adds behavioral context by specifying the return fields (id, type, params, etc.) and confirming the scope is restricted to the caller's subscriptions. It doesn't mention the optional include_inactive parameter, but that's a parameter detail not a behavioral trait.

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: the first states the action and output fields, the second gives usage guidance. Every word earns its place, with no redundancy or filler. It 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?

With no output schema, the description compensates by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count). The tool has only one optional parameter, and the description provides enough context for the agent to decide when and how to use it. The annotations and schema together with the description make it complete.

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

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

The schema provides 100% coverage for the only parameter (include_inactive) with a description: 'Include cancelled subscriptions in the response (default false).' The tool description does not add any extra meaning about the parameter beyond what the schema already states. This aligns with the baseline of 3 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools like subscribe/unsubscribe by scoping to the caller's subscriptions. It also lists return fields, which removes any ambiguity about what the tool does.

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

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

The description explicitly provides usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool (before adding subscriptions, when needing an id to cancel) and implicitly contrasts with subscribe/unsubscribe tools.

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

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

Annotations are minimal (readOnlyHint=false, etc.) but the description compensates by disclosing rate limits ('5 per identifier per day'), the behavior of claim_token (returns a token, can be passed later to read status), and the fact that filing is free and doesn't count against quota. It also notes the team's response cadence. This adds significant 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 informative but somewhat lengthy. It packs a lot of guidance into a few sentences, but the paragraph form and multiple clauses make it dense. It earns a 4 because every sentence adds value, but it could be better structured (e.g., bullet points).

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

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

The tool has 4 parameters (all optional), a nested context object, and no output schema. The description covers all main aspects: purpose, examples of usage, limitations, rate limits, and return behavior. The lack of an output schema is mitigated by explaining claim_token's return semantics. This is complete for its complexity, though a note on the general response format (e.g., when not using claim_token) would round it out.

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

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

The schema already provides 100% description coverage, so the baseline is 3. The description enhances understanding by explaining that claim_token can be used as a standalone lookup ('with no other arguments') and that message should be specific and 1-2 sentences. However, most parameter detail is already in the schema, so this is a modest increment.

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 ('Tell... something is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx team) and the kinds of feedback (bug, feature, data_gap, praise). It also distinguishes from sibling tools by explicitly limiting to tools served by this Pipeworx connection and contrasting with 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 scenarios (bug, feature/data_gap, praise) and when-not-to-use (feedback for other MCP servers). It even provides a decision rule for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists') and instructs not to paste end-user prompts. This is exemplary 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 read-only, idempotent, and non-destructive behavior, lowering the burden. The description adds valuable context: it is a self-aggregating signal derived from the CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. These details go beyond annotations and help set expectations about data freshness and privacy.

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

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

Three sentences, front-loaded with the core purpose, followed by actionable use cases and essential behavioral notes. Each sentence earns its place; no filler or redundancy. The structure is easy to scan and understand.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers everything an agent needs: what it returns, the data structure (pack, tool, count), caching behavior, and use cases. Annotations cover safety profile, so no additional disclosure is required. The description is complete and self-sufficient.

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

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

Schema coverage is 100% and the parameter description already explains the 'window' enum and the trade-off between shorter and longer windows. The tool description repeats this information without adding new semantic details. It does mention output fields (pack, tool, count) but that's not directly parameter semantics, 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 clearly states the tool's function: showing what other AI agents are calling on Pipeworx, and specifies the outputs (top tools, top packs, total call volume). It distinguishes this from sibling tools like ask_pipeworx (which answers questions) and discover_tools (which likely recommends tools) by focusing on aggregated usage trends. The verb 'Returns' plus explicit resource and window scope make it very specific.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It also implies when not to use it (for actual questions or deep research), but doesn't name alternative tools or state exclusions, 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?

Even though annotations already include readOnlyHint, openWorldHint, and idempotentHint, the description adds crucial behavioral details beyond them, such as the FILL CHECK mechanism, the meaning of realizable_edge_pp <= 0, the PARTITION FILTER's placeholder logic, and the SEMANTIC ANCHOR's Jaccard similarity threshold. This explains side effects and edge-case behavior far beyond structured hints.

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

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

The description is long but every sentence earns its place. It is logically structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and mode overview. The density is justified by the tool's complexity, and it avoids 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 complex tool with no output schema, the description thoroughly explains response shapes (opportunities[] with fields, partition_check object), caveats (fill check, placeholders), and failure modes (realizable_edge_pp <= 0). It covers both parameter modes and operational edge cases, making it 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?

Schema coverage is 100%, but the description greatly expands on the bare schema. For 'event', it explains slug format, accepts full URLs, and describes how it walks child markets. For 'topic', it defines a 'seed question' and explains cross-event flattening and union checks. This adds meaning far beyond the schema's one-line property descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from siblings by detailing three modes (no args, event, topic) and explicitly references polymarket_fill_risk for custom sizing, distinguishing it from polymarket_edges and similar 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 provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan...' and says 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing and explains cross-event mode's unique capability, giving clear situational direction.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds substantial behavioral detail: caching at 'KV level keyed on all knobs,' filtering behaviors (placeholder-slug filter, partition placeholder fraction), output semantics (edge_pp_net, kelly_fraction, 24h-move warning), and model caveats. 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 long but dense with important details. It is structured using all-caps section headers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) which aids navigation. Every sentence adds substantive information, but it is still a large wall of text that could overwhelm at first glance.

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 comprehensively covers the response structure: top-level keys (by_segment, fed_candidates, _diagnostics), the contents of each segment, and the diagnostics funnel for understanding empty results. It also explains caching and tradeable-edge filters. No major gaps for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context that clarifies nuanced parameter behavior, such as why min_kelly doesn't apply to partition_overround (parent-level kelly_fraction_half=0) and how slippage_pp interacts with Polymarket's fee structure. This extra explanation lifts the score 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 core purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the use case as 'what should I bet on today.' While it doesn't explicitly compare against siblings like polymarket_edge_tracker, the detailed segment descriptions provide enough 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 strong usage context with 'Built for what should I bet on today' and explains when certain segments are rare-by-design and that Fed bets are 'excluded from ranking' due to unreliability. However, it doesn't name alternative tools or explicitly say when NOT to use this tool in favor of a sibling.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes well beyond by explaining data gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), the 60-day TTL limit, and that decay numbers come from daily closes, not intraday. It also details the response structure (tracked/expired/snapshot_dates), providing rich behavioral context that annotations cannot convey.

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

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

The description is dense but well-structured: purpose first, then args, response format, and limits. Every sentence carries meaningful information, and the format guides the reader through complex telemetry concepts without waste. The length is appropriate given the tool's complexity.

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

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

Despite having no output schema, the description fully specifies the response shape (tracked[], expired[], snapshot_dates[]) and explains key fields like trend, decay_pp_per_day, and lifespan_days. It also covers data limitations (TTL, cache-miss gaps) and the meaning of negative edge_pp_net. This is complete for an agent to select and interpret the tool's output.

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

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

Schema coverage is 100% and both parameters are already documented with defaults and constraints. The description adds the concept of 'snapshot family' and restates the lookback window, but does not provide examples or additional semantic nuance beyond what the schema already offers. This meets the baseline for high schema coverage without adding significant value.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It then answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges by focusing on history/decay rather than current edges. This is unambiguous and differentiates the tool.

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

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

The description gives clear context: a fresh wide edge and a 3-week-old wide edge are different trades, implying this tool is for evaluating edge persistence before acting. It also frames the median lifespan as a competition clock. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full when/when-not guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds rich behavioral context: explains the two modes, what happens on partial fills, the risk of unhedged directional positions, and the verdict states. No contradiction with annotations.

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

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

The description is long but densely packed with necessary detail. It front-loads the core purpose and then systematically covers modes, parameters, return fields, and usage warnings. Some structure (e.g., line breaks between modes) could improve scannability, but 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 complex tool with no output schema, the description thoroughly explains return values (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.), both operational modes, parameter semantics, and even edge-case risks. Nothing major is unaddressed.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: clarifies size_usd interpretation in both modes (max spend vs target proceeds vs settlement notional), explains side defaults and auto-detection in basket mode, and notes clamping (10–1,000,000). This goes well beyond the baseline.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and realizable edge.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also names alternatives implicitly and warns against theoretical overround on thin books.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description goes well beyond them: it enumerates compatibility codes, specifies that unclassified legs are never paired, explains that pairing_unverified is set whenever pairs are returned, discloses gross-versus-net fee treatment, and clarifies null semantics for temporal_alignment. No statement contradicts the annotations.

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

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

The description is long but well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS), front-loads the core purpose, and packs safety-critical detail without stream-of-consciousness. Some redundancy—such as repeated emphasis on both modes running the same matcher and 'pre-mapped ≠ tradeable'—keeps it from being maximally concise.

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

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

With no output schema, the description carries the burden of explaining return values and does so comprehensively: response shape, top_spreads_pp flags, compatibility codes, skipped counters, fees_note, and temporal_alignment null semantics are all covered. It also explains parameter relationships and sets realistic expectations about data quality, making the tool fully actionable.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful beyond-schema semantics by explaining the override relationship between `topic`, `kalshi_event_ticker`, and `polymarket_event_slug`, and by listing the exact pre-mapped topic values. This lifts it above the baseline, though the schema already documents each parameter.

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

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

The description opens with a precise statement—'Cross-venue spread between Kalshi and Polymarket for the same resolving question'—and then details two modes and the response shape. It is unmistakably clear about what the tool computes, though it does not explicitly position it against sibling tools like polymarket_arbitrage.

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

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

The description gives explicit mode-selection guidance: use `topic` for pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, noting both modes run the identical matcher. It also sets expectations by warning that most pre-mapped topics return compatibility warnings and are not tradeable. It stops short of naming alternative sibling tools for when this tool is not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds valuable context beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys by omitting the key. This provides behavioral nuance about data isolation and default output, though it doesn't cover error cases or empty results.

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

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

The description is two sentences with no filler. It front-loads the primary function, then gives a concrete use case and scoping detail, and finally points to companion tools. Every clause serves a distinct purpose.

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

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

For a simple one-parameter tool with strong annotations, the description covers purpose, usage context, scoping, and relationship to siblings. It is sufficiently complete without needing return-format details since no output schema exists. The description provides all necessary information for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% for the 'key' parameter, so the baseline is 3. The description adds semantic value by explaining that omitting the key lists all saved keys, which is not explicit in the schema. This extra instruction enriches the parameter meaning.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the resource (saved memory) and verb (retrieve/list), and distinguishes from sibling tools by explicitly referencing remember and forget as companions.

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 a clear use case: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names alternatives (remember to save, forget to delete), giving explicit pairing guidance. This meets the 'when and with what' 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 declare readOnlyHint=true, destructiveHint=false, but the description states mark_read:true flags events read and affects future calls, implying a state mutation. This directly contradicts the readOnlyHint annotation, so per the rubric the score is 1. Annotation Contradiction flagged.

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 packed with useful information: purpose, return content, filtering, read-state semantics, and an alternative endpoint. It is front-loaded with the main action and every sentence contributes.

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 explains what each alert carries (source, citation_uri, raw payload). It also covers read-tracking behavior, polling suitability, and an equivalent HTTP endpoint, making it complete for a list/feed tool. The contradiction does not reduce completeness here.

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

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

Schema covers all 5 parameters, so baseline is 3. The description adds meaningful context for mark_read (explaining its downstream effect), gives a concrete type example, and clarifies the since timestamp format, which exceeds the baseline.

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

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

The description clearly states the tool pulls fired events from a subscription feed, with a specific verb and resource. It does not explicitly call out sibling alternatives, but the 'subscription feed' framing differentiates it from generic 'events' or 'recent_changes' tools.

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

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

The description gives concrete usage context: polling is supported, filtering by type and since, and setting mark_read to advance the feed. It also mentions the same feed is available at a GET endpoint for scripts/dashboards, which helps choose the right access method. No explicit exclusions, but clear enough.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral detail: data source fallbacks, API sunset soft-fail for USPTO, parallel fan-out, and return structure (changes[] grouped by source, total_changes, citation URIs). 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 tightly packed with useful information. The opening query examples are somewhat redundant, but they serve as usage cues. Each subsequent sentence earns its place, covering sources, fallbacks, parameter format, return values, and an alternative tool. Slightly over-explained 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?

Given the tool's complexity (multi-source fan-out, fallback, sunset), the description is thorough: it explains behavior, return format, parameter semantics, and when to choose a different tool. No output schema exists, but the description covers return structure adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'since' applies to all sources ('filings since since', 'news mentions in window') and by recommending '30d' or '1m' for typical monitoring. This connects parameters to actual behavior beyond the schema's bare descriptions.

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

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

The description clearly states the tool's function: a change feed for a company over a time window, with a specific verb ('change feed') and resource ('company'). It distinguishes itself by detailing its multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with entity_profile for static needs.

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 via natural language examples and clarifies the alternative: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior (GDELT preferred, GNews on rate limits) and the 'ONE parallel call' efficiency, giving clear context for choosing this tool.

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

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

Annotations already set idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds meaningful behavior beyond this: persistence across sessions vs. 24-hour anonymous retention, key-value scoping by identifier, and authentication-dependent lifetime. It does not mention overwrite semantics on duplicate keys, which would be valuable, but the provided context is solid.

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 four sentences but each earns its place: purpose, use cases, storage model, persistence semantics, and companion tools. It is front-loaded with the action and avoids filler.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, usage cues, persistence details, and related tools. Missing details like overwrite behavior or key constraints are minor for this tool class. The annotation hints plus description make the tool ready for correct invocation.

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

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

Schema coverage is 100%: both 'key' and 'value' are described with examples. The description adds little beyond schema, just 'key-value pair' and general examples already in the schema. 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 opens with a specific verb+resource: 'Save data the agent will need to reuse later,' then gives concrete examples (ticker, address, user preference) and clearly distinguishes from siblings (recall, forget) by explicitly naming them.

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 when you discover something worth carrying forward' and lists example triggers. It also names alternatives/companion tools ('Pair with recall to retrieve later, forget to delete'), making the decision context clear.

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

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

Annotations already declare readOnly, openWorld, and idempotent, and the description adds substantial behavioral context: graceful degradation when LEI/FIGI providers are unavailable, explicit labeling of identifier sources, explicit `unresolved` reporting, returning `figi_candidates` on ambiguous matches, and the fact that each call cascades through several internal lookups. No contradiction with annotations.

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

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

The description is long, but almost every clause earns its place by specifying identifiers, sources, edge cases, or input constraints. It front-loads the purpose and usage rule before the detailed type breakdown. Slightly overstuffed with parenthetical asides, so it is not a 5, but it is exceptionally information-dense rather than padded.

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 burden of explaining what the agent will get back. It covers returned identifiers per type, source labeling, unresolved handling, ambiguous-match behavior, degradation under provider outages, and accepted input formats. An agent has everything needed to invoke this tool correctly and interpret its 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%, giving a baseline of 3, but the description goes well beyond it. For `value` it warns to pass only the entity name, not the full noun phrase, because trailing security-class words will break FIGI matching. For `type` it explains supported entity types and the exact identifier sets returned for each, adding meaning the enum alone cannot convey.

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

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

The description opens with concrete user-phrase examples and then states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from siblings like entity_profile or search_within by defining its role as the identifier-resolution entry point for companies and drugs.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details type-specific behavior, including when ambiguity should result in figi_candidates rather than an assertion. It does not explicitly name sibling tools as alternatives or state when not to use it, but the intended use context is unmistakable.

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, so the safety profile is clear. The description adds the output format (XML text), which is useful, but it does not disclose behavioral traits like the source of the RSS feed or how the feed is determined.

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, but it is a sentence fragment rather than a complete sentence. It is front-loaded with the key output format, but it lacks essential details, which prevents a higher score.

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 zero parameters and an output schema, the description should still explain what RSS feed is returned and how it relates to other tools. The current text is too ambiguous to be considered complete, leaving the agent guessing about the tool's purpose.

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

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

There are zero parameters, so the description is not expected to explain parameter semantics. The input schema is empty, and the description's mention of 'XML text' adds minimal context, but the baseline for zero parameters is 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 'Raw RSS feed (XML text)' is a noun phrase without a clear verb or resource. It does not specify what action the tool performs or what feed it returns, and it does not distinguish this tool from sibling tools like 'geojson' or 'events'.

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 description provides no context, prerequisites, or exclusions, leaving the agent without any basis for selecting this tool.

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

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

Annotations already indicate safe read-only behavior. The description adds valuable context by revealing it internally calls ai_visibility_check per entity, ranks by score, and returns specific fields (score, confidence, signal density). This goes beyond the annotation baseline and provides useful behavioral insight 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 three sentences long, front-loaded with the main purpose, and every sentence earns its place: the first defines the action, the second explains mechanics, and the third gives a concrete use case and return value. No wasted words.

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

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

Without an output schema, the description compensates by explicitly naming the return payload ('ranked list with score, confidence, signal density per entity'). It also explains the internal workflow and a realistic usage scenario. Minor omissions like error handling or interpretation of confidence are not critical for a read-only comparison tool.

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

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

Schema description coverage is 100%, and each parameter has a meaningful description in the schema (e.g., entities array, optional models, context disambiguation). The tool description itself does not add extra parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource combo: 'Compare AI visibility across multiple entities side-by-side.' It further distinguishes itself from the sibling tool ai_visibility_check by explicitly mentioning it probes each entity with that underlying tool and ranks results, making it clear this is a comparative multi-entity version.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and even quotes an example question. It implies this tool is for comparing multiple entities, which distinguishes it from the singular ai_visibility_check, but it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds crucial behavioral context: it fans out to two external services, it degrades gracefully on partial failures, and bundlephobia's first measurement can take 5-30s and may time out (with sources_failed reporting). This goes beyond the annotations and helps set agent expectations.

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

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

The description is appropriately sized for a composite tool. Each sentence earns its place: purpose, usage trigger, return structure, ecosystem limitation, and failure behavior. It is front-loaded with the most important information and does not waste words.

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

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

No output schema exists, so the description must explain return values. It details the summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also covers ecosystem scope and partial failure behavior, making it highly complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for the parameters; it mentions 'npm package' and version history but the schema already documents scoped packages and defaulting behavior. No extra constraints or formats are given, so it neither improves nor degrades the baseline.

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

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

The description opens with a specific, compound purpose: 'Composite "should I add this npm package to my project" check in ONE call' and lists exact data sources (deps.dev, bundlephobia). This distinguishes it from sibling tools focused on betting, research, or visibility, and uses an action verb ('scan/check') with a clear resource (npm package).

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 usage trigger is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an explicit alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), clearly indicating when NOT to use this tool.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the truncation cap (200K chars, flagged), the use of BGE-base-en embeddings and cosine similarity, overlapping 500-char windows, and the output structure (character offsets and similarity scores). This level of technical detail helps the agent anticipate edge cases and limitations.

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 earns its place: purpose, usage condition, pairing, and technical behavior. It is front-loaded with the core definition and structured logically, making it easy to parse without being verbose.

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

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

With no output schema, the description must explain return values, and it does: 'top-N passages with character offsets and similarity scores.' It also covers input limits, truncation, and the relationship to ask_pipeworx_grounded. This gives an agent everything needed to invoke the tool 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 baseline is 3. The description adds meaningful context: 'text you already pulled' clarifies the source, and the query examples ('supply-chain risk', 'fiscal year 2024 revenue') illustrate expected natural-language input. It enriches the parameters beyond the schema's basic type descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which clearly states a specific verb (search) and resource (fetched record). It further distinguishes itself from siblings by naming ask_pipeworx_grounded as a complementary tool, not an alternative with the same function.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions the alternative ask_pipeworx_grounded with a pairing strategy. This gives clear decision criteria for choosing this tool over related ones.

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

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

The description claims to create a new subscription and returns a new subscription id, which directly contradicts the idempotentHint=true annotation. While it adds rich detail about auth, delivery, and limits, this fundamental contradiction makes it misleading about repeat-call behavior.

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

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

The description is dense but well-structured: purpose first, then supported types, delivery channels, and requirements. Every part earns its place, though a small amount of redundancy with the schema's parameter descriptions exists.

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 creation tool with no output schema, it covers return value, auth prerequisites, all subscription types with examples, delivery channels, rate limits, and failure behavior (webhook auto-disable). This is complete enough for an 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?

With 100% schema coverage, the description still adds value by mapping concrete examples to specific types (e.g., sec_8k items:["5.02"] = officer change) and clarifying the meaning of delivery options beyond the schema's already-detailed descriptions.

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

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

The description opens with a specific verb-resource pair ('Create a proactive monitoring subscription to a live-data event stream') and clearly distinguishes the tool from its siblings (list_subscriptions, unsubscribe, recent_alerts) by focusing on the act of subscribing and returning a 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?

It provides clear context for when to use the tool (setting up monitoring for specific event types) and how to configure it, but it never explicitly contrasts with alternatives like using 'events' or 'recent_alerts' for one-off checks, nor does it state when not to subscribe.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description adds value by detailing the exact return format (category-bucketed example questions), the two invocation modes (no args vs topic), and that results are 'drawn from the live catalog of thousands of tools.' 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 dense but front-loaded with example prompts that immediately convey intent. Every section earns its place, although the list of seven paraphrased prompts could be trimmed to reduce verbosity without losing value.

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

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

With no output schema, the description fully covers what the tool returns, how to invoke it (both modes), and why/when to use it. For a simple onboarding tool, this leaves no significant gaps; the behavior, purpose, and parameter semantics are all clearly explained.

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

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

Schema coverage is 100% for the single optional topic parameter, so baseline is 3. The description enhances this by providing concrete examples ('finance', 'pharma', 'betting') and explaining default behavior ('Call with no arguments for the full spread'), which goes beyond the schema.

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

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

The description explicitly states this is 'the onboarding entry point' that 'returns category-bucketed example questions' with 'the exact tool + argument shape.' This clearly distinguishes it from sibling tools like ask_pipeworx (which answers queries) and discover_tools (which likely lists tools). The opening list of example prompts reinforces this purpose.

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

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

The description gives clear when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools.' It also names alternatives (ask_pipeworx, entity_profile, compare_entities) but stops short of explicit when-not instructions, relying on 'FIRST' to imply you should move on after onboarding.

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

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

The annotations already indicate non-read-only and idempotent, but the description adds critical behavioral details: ownership enforcement and soft-delete semantics (deactivated, not deleted, history preserved). This goes well beyond what annotations provide.

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

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

Three sentences, each adds substantive information (operation, ownership, deactivation behavior). No redundant content; well front-loaded with the core action.

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

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

For a single-parameter mutation with no output schema, the description adequately explains the effect, side conditions, and historical data access, making it complete for selection and 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% with a clear description of 'id' (uuid returned by subscribe). The description only reiterates 'by id' without adding new parameter-specific meaning, so the schema carries the burden.

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 'Cancel' with the resource 'subscription by id', clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. It also adds scoping details (ownership enforced, deactivation vs deletion) that further differentiate the tool.

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

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

It provides clear context: ownership is enforced, and deactivation preserves historical events via 'recent_alerts'. However, it doesn't explicitly contrast with alternatives or state when not to use it, so it falls 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?

Beyond annotations, it discloses the fast-path vs grounded pipeline behavior, the exact math for financial claims, and crucial error semantics: could_not_verify indicates the check did not happen and must not be treated as evidence, while unsupported means no source covers it. These traits are not inferable from 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 structured effectively: intent examples, routing logic, return output, and caller warnings are each front-loaded and distinct. Every sentence adds necessary context for correct invocation, and the length is justified by the tool's complexity.

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

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

With no output schema, the description fully enumerates the verdict vocabulary, return components (verdict, value, citation, reasoning), and explicitly defines could_not_verify vs unsupported. Combined with the 100% schema coverage, it leaves no critical ambiguity for callers.

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 claim and tolerance_pct fully described, including default and override semantics. The tool description adds no parameter-level detail beyond restating the percent-delta math, so the baseline of 3 applies.

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

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

The description opens with natural-language examples ("Is it true that…", "fact check") and explicitly states "natural-language claim verification against authoritative sources." It clearly differentiates from siblings by noting it consolidates 4–6 sequential steps, and explains the two routing paths (SEC EDGAR/XBRL vs grounded fallback).

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

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

It says "Use whenever the agent needs to check whether something a user said is factually correct," and further distinguishes company-financial claims from any other factual claim. However, it does not explicitly name alternative sibling tools or state when not to use it, so it falls short of full exclusion guidance.

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