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 indicate read-only/idempotent behavior, and the description adds context about returning citation URIs, routing through thousands of tools, and being a fast single call. It also implicitly sets expectations about not doing deep research, referencing siblings as escalation paths. 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 the 'PREFER OVER WEB SEARCH' directive, followed by scope, mechanism, examples, and escalation paths. Every sentence carries guidance, though some redundancy exists (e.g., 'START HERE' and 'default entry point'). It's long but well-organized for an agent.

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?

Even without an output schema, the description sets expectations for the return value (structured answer with citation URIs) and operational characteristics (works on every tier, one fast call). It also clarifies the tool's scope boundaries by referencing siblings for deeper or broader research. This makes it complete for a read-only lookup tool.

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

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

Schema descriptions cover all six parameters (actually aliases for the same question field) with 100% coverage, so the description doesn't need to add much. The only extra seasoning is the list of example questions, but those are usage examples rather than semantic clarification of the parameter. Thus a baseline 3 applies.

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

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

Clearly states the tool routes questions to appropriate sources and returns structured answers with citations. Distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning as the default fast entry point, and specifies the resource (5,529 tools, 1455 sources).

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

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

Explicitly says to prefer over web search for factual questions and to start here for most questions. Gives clear when-not guidance by naming alternatives for hallucination-resistant answers (ask_pipeworx_grounded) and broad/multi-part queries (deep_research), plus explains coverage for breaking news. This exceeds a simple usage statement.

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

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

The description adds valuable behavioral context beyond the annotations: it is an experimental beta, may have routing changes tested live, and currently matches ask_pipeworx exactly. The statement 'Falls back to nothing — this IS a full working router' prevents misinterpretation. This aligns with the readOnly, openWorld, idempotent, and non-destructive 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 four sentences, front-loaded with the key identity ('Beta version of ask_pipeworx'), and each sentence contributes useful context about current state, usage, and behavior. It is slightly verbose but appropriately detailed for a beta variant with dynamic routing behavior.

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

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

Given no output schema and a relatively simple parameter set, the description covers what the tool is, when to use it, current behavior, and its relationship to the stable ask_pipeworx. It relies on 'same response shape' to reference the sibling's output format, which is acceptable for a variant tool, but does not fully describe the response structure on its own.

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 the 'question' property described as a natural-language request and all five aliases documented. The description adds no extra parameter semantics but does not need to, as the schema fully explains the six parameters. Baseline 3 is appropriate.

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

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

The description clearly identifies it as a beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable ask_pipeworx sibling by mentioning experimental routing improvements. It answers what the tool does (routes questions to many tools) and how it differs from its sibling.

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

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

It explicitly says to use it 'exactly like ask_pipeworx' and specifies the condition 'when you want the newest routing.' It also notes no candidate is active, so behavior currently matches stable. However, it does not explicitly state when not to use it (e.g., for production stability), leaving an implied exclusion rather than an explicit one.

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

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

Annotations already indicate readOnly/idempotent/non-destructive, but the description adds crucial behavioral details beyond those: the extra LLM call cost, the refusal mechanism with explicit reasons (not_in_source, no_tool_match, etc.), and the strict grounding to only tool result content. This directly enhances an agent's ability to anticipate outcomes.

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

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

The description is longer than average but every clause earns its place: purpose, routing, return format, refusal behavior, use cases, and cost tradeoff. It is front-loaded with the core value proposition. Slightly verbose but not wasteful, earning a 4 rather than a 5.

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

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

Given the complexity and the absence of an output schema, the description fully covers the return contract (success and refusal shapes), routing behavior, cost implication, and usage policy. An agent has all necessary context to decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, with all six parameters being aliases for 'question' and each having a description. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's specific purpose and differentiates it from siblings. It explicitly contrasts with ask_pipeworx ('Same routing as ask_pipeworx') while highlighting the grounded extraction behavior, and even names alternatives for different use cases.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims). It also states when not to use it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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?

Rich behavioral disclosure beyond annotations: returns gaps[] for unanswered questions, never invents facts, includes contradictions[] for deeper depths, guarantees fetchable citations, explains semantic excerpting, and gives latency expectations. Annotations already state read-only/open-world, and the description complements 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 a dense paragraph with many clauses, but every sentence adds value. It is not perfectly structured (could use bullets for depth options), but the complexity of the tool justifies the length and it remains readable and front-loaded with the most critical account requirement.

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 describes the return format: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers time expectations, account tiers, and alternatives, making it complete for a complex tool.

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

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

Schema covers both parameters, but the description adds crucial nuance: depth values are fully explained (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop), and question is described as natural-language, broad/multi-part acceptable. This goes well beyond the schema's enum text.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself from open-web search. It clearly differentiates from siblings like ask_pipeworx by emphasizing parallel decomposition and citations.

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

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

Provides explicit guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account prerequisites and when to fall back to ask_pipeworx 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 annotations (read-only, idempotent, open-world), the description discloses fan-out sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific output fields, limits (up to 5 filings), soft-fail for patents API sunset, and GDELT→GNews fallback. These are meaningful behavioral details 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 long but dense, front-loaded with example queries and followed by a structured list of returned fields. A bulleted format would improve scannability, but every clause contributes meaningful context for a complex multi-source tool.

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 so thoroughly: listing exact fields, sorting, limits, source fallbacks, and soft-fail behavior. It also covers input constraints and alternatives, making it complete for the tool's complexity.

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

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

Schema covers both parameters fully, so baseline is high, but the description adds concrete examples ('AAPL', '0000320193'), clarifies zero-padding, and reinforces that names are unsupported. It also adds a cross-tool pointer to resolve_entity, which is helpful 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?

Description uses a strong verb ('profile') with explicit scope: 'full cross-source profile of a US public company'. It provides numerous example queries and explicitly contrasts itself with 'chaining single-pack SEC/XBRL/news lookups', clearly distinguishing it from sibling tools.

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

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

States a clear preference: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides eligibility constraints: accepts ticker or CIK only, and directs users with only a name to resolve_entity first.

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=true, openWorldHint=true, and idempotentHint=true. The description adds significant behavioral context: the meaning of compatibility_warning in two distinct cases, temporal_alignment semantics, and the skipped_cross_type/subtype counters. It also discloses that most pre-mapped topics return compatibility_warning today. 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 well-structured with clear sections (modes, response, safety fields). It front-loads the core purpose and then adds necessary detail. Minor redundancy exists, such as repeating the topic list that also appears in the schema, but the complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining the return values. It thoroughly describes leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning triggers, temporal_alignment, and skipped_cross_type/subtype counters, covering edge cases and limitations. This is complete for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the mode selection (topic vs explicit) and the override behavior of kalshi_event_ticker and polymarket_event_slug relative to the topic-mapped side, which is not apparent from the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with explicit mention of two modes and response details. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison rather than intra-venue 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 provides explicit usage guidance: it explains the two modes (topic shortcuts vs explicit ticker/slug), spells out when compatibility_warning fires, and warns that pre-mapped topics often are not tradeable, suggesting users should verify with explicit pairings. This effectively tells an agent when and how 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?

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, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond this: it says the tool cascades through several lookup endpoints internally, degrades gracefully (LEI/FIGI enrichment unavailable still returns EDGAR identifiers), and explicitly states that unresolved identifiers are listed under `unresolved` rather than omitted. It also mentions source labelling for identifiers, which is crucial for trust.

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

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

The description is relatively long but well-structured. It front-loads the purpose with example queries, then gives concrete usage guidance, and finally details supported types and behavior. Every sentence adds value, especially given the tool's complexity (two entity types, multiple identifiers, conditional enrichment). It is slightly verbose but not wasteful, earning a 4 rather than a 5.

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

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

With no output schema, the description must explain what the tool returns, and it does so thoroughly: for company it lists CIK, ticker, company_name, LEI, FIGI; for drug it lists RxCUI, ingredient, brand, and a citation. It also covers error/edge behavior (unresolved field, graceful degradation) and internal cascading, making it complete for a tool of this complexity. This fully compensates for the absence of an output schema.

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

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

Schema coverage is 100% and both parameters have descriptions that already specify accepted formats (ticker, CIK, or name for company; brand or generic for drug). The description does not add unique semantics beyond providing examples like 'AAPL' or 'ozempic' and clarifying that company accepts multiple input types. Since the schema already carries the parameter detail, a baseline score of 3 is appropriate, with the description offering mild reinforcement.

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

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

The description clearly states the tool resolves a name to canonical/official identifiers, with specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings like entity_profile and compare_entities by positioning itself as the entry point for ID lookups, and lists example queries that make its purpose immediately recognizable.

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

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

The description gives explicit usage direction: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use the tool, and by implication when not to (when ID is already known). It also mentions it replaces 2-3 manual lookups, justifying its role as a consolidation tool, and differentiates between company and drug types with separate use cases.

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.