Vessel Tracking

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

Annotations already declare readOnlyHint=true,openWorldHint=true,idempotentHint=true,destructiveHint=false. The description adds meaningful behavioral context: it 'listens' for a time window and reports whether a receiver covers the point, clarifying how to interpret false negatives. Does not contradict annotations.

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

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

Two well-structured sentences, front-loaded with a question and a clear functional statement. The second sentence provides direct usage guidance. No filler or redundancy.

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

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

The description covers purpose, usage scenario, and interpretation of results. Without an output schema, it conveys the result type ('reports whether any community receiver covers it') but leaves slight ambiguity about the exact return format. Overall very complete for a simple check 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 100% of parameters, so baseline is 3. The description adds no extra parameter syntax but implicitly references latitude/longitude and listening time through 'at this location' and 'Listens.' Schema already explains each parameter's purpose.

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: 'Listens at a point and reports whether any community receiver covers it.' It uses a specific verb ('listens') and resource ('receiver coverage'), and distinguishes itself from sibling ship-tracking tools by focusing on receiver presence rather than ship positions.

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 directs when to use the tool: 'Use this whenever a vessel search comes back empty, and always before treating an empty result as evidence that shipping has stopped.' This provides clear context and helps differentiate it from alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds key behavioral context: default model is free Workers AI Llama-3.3-70b, enabling Anthropic requires a BYO API key with direct payment, and the return payload structure (per-model score, confidence, signals, raw_response + combined view) is disclosed. This is valuable transparency for a read-only probing tool and is consistent with 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 three sentences, front-loaded with the core purpose, then details on defaults and API key usage, and finally use cases. Every sentence earns its place with no filler or redundant restating of the tool name.

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 explicitly listing the return format (per-model {score, confidence, signals, raw_response} + combined view). It also covers the key parameters (default model, optional _apiKey, models array) and gives specific use case examples. This is complete for a tool with 4 params and no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the default model behavior (workers-ai is free) and that _apiKey is specifically for Anthropic with direct payment, which goes beyond the schema's descriptions. It also reinforces the optional nature of models and context without repeating schema details verbatim.

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 0-100 per model. It uses a specific verb ('probe'), names the resource (business/brand/product/topic), and defines the output (score per model), making it distinct from general-purpose AI tools. The use cases (AI-marketing audits, pre-launch checks) further contextualize the 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 explicitly lists practical use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring', which tells users when to reach for this tool. It does not explicitly mention alternatives or when not to use it, but the context signals are strong enough that a user can infer appropriate usage compared to sibling tools like ask_pipeworx or compare_entities.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable behavioral context beyond annotations: it routes to 5,322 tools, returns stable citation URIs, works on every tier, and makes a single fast call. It does not detail error/rate-limit behavior, but with annotations providing safety profile, the added context is strong.

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 sentence serves a purpose: it starts with a strong recommendation, lists data domains, describes behavior, provides trigger phrases, gives examples, and outlines escalation paths. It's front-loaded with 'PREFER OVER WEB SEARCH' and is well-organized despite its length.

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

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

Given the tool's broad scope and many siblings, the description is exceptionally complete. It covers when to use the tool, what to expect (structured answer with citations), performance characteristics (one fast call), applicability across tiers, and explicit alternatives. This fully equips 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 aliases fully documented. The description goes beyond the schema by providing specific example questions and clarifying the nature of the question ('what is', 'look up', 'find', current facts about real-world entities'), which helps the agent phrase queries appropriately. This adds practical value beyond the schema's technical 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: 'Routes the question to the right one of 5,322 tools across 1393 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses specific verbs (routes, fills, returns) and differentiates from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It also says when to step up: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This clearly establishes appropriate usage versus 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?

With annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds valuable behavioral context: it is experimental, may have routing changes when candidates are tested, currently matches ask_pipeworx exactly, and results are compared to decide merges. It also clarifies the 'falls back to nothing' aspect, ensuring the agent knows it is fully functional and not a stub. 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 concise sentences, front-loaded with the essential purpose. Every sentence earns its place: definition, current state, usage guidance, and experimental nature. No redundancy or fluff.

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

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

For a beta tool with no output schema, the description is remarkably complete. It specifies the full tool count, identical response shape, the current inactive candidate status, usage instructions, and how results are compared. It gives the agent all necessary context to invoke and interpret 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 all six parameters (question and five aliases) already documented clearly. The description mentions 'same arguments' but adds no extra semantic detail beyond what the schema provides. Baseline 3 is appropriate since 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 clearly states that this is a beta version of ask_pipeworx, an identical universal router with the same 5,322 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by being the experimental edge with candidate routing improvements. This is a specific verb+resource description that differentiates well.

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 tells when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It implies the alternative (ask_pipeworx for stable routing) and clarifies that this is a full working router with no fallback, so there is no ambiguity about when 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?

The description reveals detailed behavior beyond the annotations: it returns evidence, confidence, source, and an explicit refusal_reason list, and explains it only uses the tool result. It also discloses the extra LLM call cost. This is far beyond the readOnlyHint and idempotentHint, providing rich, non-obvious context.

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

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

The description is dense but every sentence earns its place: it defines the mode, explains the output contract, states use cases, and gives the cost/alternative. The structure front-loads the core purpose and then details edge cases without irrelevant 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?

The tool is complex with success and failure states, but the description covers both, including refusal reasons, evidence quotes, and when to prefer the sibling. With no output schema, the description compensates fully by defining the return shape. Annotations are also rich, making this contextually complete.

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

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

Schema coverage is 100% with the question parameter and all aliases fully described in the schema, so the baseline is 3. The description adds little parameter-specific detail beyond noting the tool 'fills arguments' internally, which is not needed given the single question input.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' that fetches via routing and extracts answers strictly from tool results, distinguishing it from the sibling ask_pipeworx. It specifies the resource (Pipeworx tools) and the verb (extracts grounded answers), making the purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' This gives clear decision guidance relative to the sibling tool, including a cost trade-off.

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 extensively discloses behavior beyond the readOnly/idempotent annotations: it explains the resolver contract with market_match_confidence, the low_confidence_match and market_closed_or_inactive blocking paths, wide-spread illiquidity handling, and cancellation-rule parsing for void settlements. It even warns about recurring flat-50¢ void losses, which is valuable risk context.

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

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

The description is long and dense, but it is structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY) and front-loads the core purpose. While verbose, every sentence carries distinct information relevant to agent decision-making. It earns a 4 for organization, though it is not concise.

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

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

With no output schema, the description fully specifies return shapes: result.market fields, analysis fields with edge/warnings, evidence keying, resolver alternatives, parent_event details, news fallback fields, and blocking statuses. This is comprehensive for the tool's complexity and leaves minimal ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explicitly illustrating acceptable formats for the market parameter (slug, URL, question text) and provides examples in the schema. It does not elaborate on depth or include_raw beyond schema descriptions, but the schema already covers those well.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on Polymarket bet research with category-specific fan-out, and the 'Use for' scenarios ('should I bet on X', 'what does the data say about Y') confirm its niche.

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

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

It provides explicit usage scenarios: 'Use for "should I bet on X"...' and lists classifier categories with fan-out examples, but it does not explicitly state when not to use it or name alternative tools. The guidance is strong but lacks exclusions, so it misses the top score.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description goes beyond by revealing that the tool executes in ONE parallel call, correctly handles off-calendar fiscal years (AAPL Sep, NVDA Jan), sorts by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is lengthy but information-dense; every sentence adds unique context, from trigger phrases to data sources to return format. It is front-loaded with usage examples, though it could be improved with bulleted structure for readability. Still, appropriate for 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 lacking an output schema, the description fully covers return value (paired data + citation URIs), sorting behavior, and data source specifics for both entity types. It also positions the tool against sibling lookups (entity_profile), making it complete for an agent deciding when to invoke it.

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

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

With 100% schema coverage, the baseline is 3. The description enriches parameter understanding by detailing what each `type` retrieves (company: latest 10-K financials; drug: FAERS counts/approvals/trials) and reinforces the expected `values` format (tickers/CIKs vs drug names), adding value beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, backed by concrete trigger phrases and examples. It also distinguishes itself from sequential single-pack lookups, making the purpose both explicit and differentiated.

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

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

The description explicitly instructs ALWAYS PREFER over sequential single-pack lookups when comparing entities, and lists trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') that signal when to use this tool. It also explains type-specific behavior, giving clear usage context.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the tool's decomposition into facets, parallel routing to 5,322 tools, and the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation). It also details the gaps[] behavior, never-invented guarantee, contradictions[] scan, semantic excerpting, and expected latency, which are significant behavioral traits 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 quite long (around 400 words) and dense, but it is front-loaded with critical account requirements and purpose. While every sentence adds some value, the length and lack of structural breaks (e.g., bullet points) reduce readability; a tighter version could convey the same information more efficiently.

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

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

With no output schema present, the description compensates thoroughly by detailing the return format (findings packet with evidence, confidence, source, citations, gaps[], contradictions[]) and behavior (semantic excerpting, latency, hop behavior). It also covers prerequisites (account sign-in) and alternatives, making it 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 coverage is 100%, but the description adds meaningful semantics: it explains that depth values map to facet counts (quick=3, standard=5, thorough=8), describes the hop behavior for standard/thorough, and mentions that thorough requires a paid plan. It also clarifies that the question parameter can be broad or multi-part, which the schema does not convey.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' in one call, and explicitly notes 'this is NOT open-web search.' It also distinguishes from siblings like ask_pipeworx, which is recommended for single lookups and current news, making the tool's purpose and scope unmistakable.

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

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

Usage guidance is explicit and actionable: it states the tool is 'Best for broad/multi-part questions over structured data,' gives example queries, and directs users to ask_pipeworx for single lookups or live/current-news topics. It also warns that non-signed-in users should use ask_pipeworx, and notes that depth:'thorough' requires a paid plan.

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

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

Beyond the read-only annotation, the description explains that results include full input schemas with curated examples and are directly callable without a second lookup. This adds useful behavioral context about the return format and readiness.

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 and front-loaded with purpose. The domain list is lengthy but earns its place by helping the agent gauge relevance, and no sentence is wasted.

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 discovery tool with rich schema coverage, the description fully covers purpose, usage, output format, and the action to take (call first). It lacks only an explicit 'when not to use,' but the context is sufficiently clear.

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

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

Schema description coverage is 100%: all six parameters are documented in the schema, including aliases. The description adds no parameter-level details, 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 'Find tools by describing the data or task,' using a specific verb and resource. It lists the domains covered and clearly distinguishes this tool as a discovery utility for browsing the available toolset.

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?

'Use when you need to browse, search, look up, or discover what tools exist' gives explicit context. 'Call this FIRST when you have many tools available' adds strong prescriptive guidance, though it does not name specific alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond this: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), notes the USPTO PatentsView API sunset with soft-fail behavior, and mentions returning pipeworx URIs. No contradiction with annotations.

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

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

The description is long but dense with essential information: examples, preference guidance, output breakdown, and limitations. Every sentence contributes to agent decision-making. It is slightly run-on but front-loaded with concrete user phrasings, making it efficient for parsing.

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

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

For a complex tool with no output schema, the description thoroughly outlines return values (CIK, filings with URIs, fundamentals, patents, news, LEI) and behavioral details (soft-fail, parallel execution). It also addresses input limitations. Given the richness of the description and annotations, the agent is well-equipped to use 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 description coverage is 100%, so both parameters are documented. The description adds meaning beyond the schema by providing concrete examples ('AAPL', '0000320193') and reinforcing the constraint that names are not supported, referring to resolve_entity. This enriches parameter understanding without duplication.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resources (profile, company) and distinguishes itself from alternatives by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups. It also differentiates from resolve_entity for name-based lookups.

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

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

Provides explicit example queries ('Tell me about X', 'research Acme') and states when to prefer it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: names are not supported—use resolve_entity first. This is explicit when/when-not guidance with named alternatives.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description's 'Delete' aligns with these. The description adds context about clearing sensitive data and that the memory was previously stored, which goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and contains no redundant wording. Each sentence adds useful context, making it appropriately sized for the tool's simplicity.

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

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

For a simple single-parameter tool with no output schema, the description covers purpose, usage scenarios, parameter semantics, and sibling relationships. The annotations provide safety profile, making the description complete without needing more detail.

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 'key' parameter, but the description adds meaning by stating it deletes a 'previously stored memory by key', implying the key is one created by remember. This adds semantic value beyond the schema's minimal description.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by explicitly pairing with 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?

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, clarifying its role against alternatives.

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

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

The description discloses the core behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining the process. However, it does not address potential failures (e.g., unreachable URLs, JavaScript-heavy pages) or rate limits, which would add further transparency.

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

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

The description is two sentences long and front-loaded with the core function in the first sentence. The second sentence efficiently lists use cases without redundancy. Every phrase adds value, making it succinct and well-structured.

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

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

The description covers the tool's purpose, process, output ('a single text blob ready to drop at site-root/llms.txt'), and use cases. With no output schema, the explicit mention of the output format is helpful. However, it lacks details on error handling or edge cases, which prevents a perfect score.

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

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

The input schema already provides 100% coverage for both parameters (url and max_links) with clear descriptions. The tool description adds minimal extra value, only implying that 'key links' relate to max_links and the output format. Given the schema's completeness, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It includes the specific verb 'generate', the resource 'llms.txt file', and elaborates on what it does (fetches, extracts, emits). This distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which focus on auditing rather than file generation.

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 lists use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it, leaving some room for improvement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds that it returns the caller's active subscriptions specifically, and lists the exact fields returned, providing useful context about scope and output beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose and return fields, followed by relevant use cases. There is no wasted wording or repetition of schema/annotation details.

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

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

For a simple list tool with one optional parameter, the description covers what it does, what it returns, and when to use it. The schema documents the parameter, the annotations handle safety semantics, and the return-field listing compensates for the lack 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?

The input schema already documents include_inactive with a description and default, giving 100% coverage. The description doesn't mention the parameter, so it adds no additional meaning beyond the schema. Baseline of 3 applies per the rubric.

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' – a specific verb and resource – and enumerates the returned fields, making its function unambiguous. It doesn't explicitly name sibling alternatives like subscribe/unsubscribe, but the use case reference to 'before adding more' and 'to find an id to cancel' implicitly distinguishes it from 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?

The description says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' which provides concrete when-to-use scenarios and implies the relevant alternatives (subscribe/unsubscribe). However, it lacks an explicit 'when not to use' or direct naming of 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?

Discloses significant behavioral nuance beyond the readOnlyHint annotation: "BEST EFFORT BY NATURE: this listens for a live broadcast rather than reading a stored position, and many vessels transmit less than once a minute, so a single call frequently hears nothing even for a ship that is definitely sailing." Also details coverage gaps (Persian Gulf, Strait of Hormuz, Gulf of Oman, Red Sea). This adds substantial context about reliability and operational characteristics.

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?

Although lengthy, every sentence earns its place: core purpose, best-effort caveat, parameter tuning, alternatives, coverage limitations, and count interpretation. Structured as a clear narrative that front-loads the purpose and then systematically addresses pitfalls. 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?

The tool has no output schema, but the description specifies the return fields (position, speed, course, navigational status, destination). It covers alternatives, coverage gaps, parameter tuning, and the probabilistic nature of results. Given the tool's complexity (live AIS, partial coverage, varied transmission rates), this description leaves no critical context missing.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds value by explaining the effect of window_seconds on hit rate ("Hit rate scales almost linearly with this... a 10-second window will usually miss and a 40-second one often succeeds"). It also clarifies that mmsi can contain one or more vessels, but this is already in the schema. The additional behavioral insight about window_seconds justifies a score above 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: "Where is a specific ship right now — live AIS position for one or more vessels by MMSI number." It clearly lists the returned data (position, speed, course, navigational status, destination) and distinguishes itself from siblings by explicitly recommending live_ships_in_area for area-based queries and vesselfinder_vessel for guaranteed last-known positions.

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 and when-not-to-use guidance: "Improve the odds with a longer window_seconds, or use live_ships_in_area if you know roughly where the ship is" and "use chokepoint_status for Hormuz/Suez/Bab el-Mandeb transit counts instead." It also clarifies the paid alternative (vesselfinder_vessel) and coverage limitations.

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

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

Description adds substantial behavioral context beyond the annotations: partial terrestrial coverage, specific exclusions (Persian Gulf/Hormuz/Red Sea), the listening-window nature of counts, and the fact that returns are only vessels heard, not a complete census. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose, then covers usage modes, coverage limitations, and return payload. Every sentence contributes unique information; no filler or redundancy. Well-structured for a complex 11-parameter 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?

Given the lack of an output schema, the description fully describes the return value (vessel fields plus type breakdown) and important caveats (partial coverage, non-complete counts). It also names an alternative tool for excluded regions, making it complete for operational 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 covers 100% of parameters, so baseline is 3. The description adds meaningful semantic context: explains the centre-vs-bounding-box alternatives, and clarifies that window_seconds affects the ability to hear anchored vessels. It does not restate every schema description, but adds 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 clearly states the tool's function: live AIS-derived ship positions for a geographic area. It specifies the resource (ships in an area) and the verb (live positions), and distinguishes itself from sibling tools like live_ship_position (single ship) and ais_coverage_check.

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

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

Usage guidance is explicit: provides both centre+radius and bounding box options, and gives an alternative tool (chokepoint_status) for areas without coverage. It also explains when to use (near ports/coastlines/coordinates) and notes coverage 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 provide no safety hints (all false), so the description carries the burden. It discloses 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota,' which are relevant behavioral constraints not visible in annotations.

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

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

About 5 sentences, front-loaded with purpose, then usage, then constraints. No fluff; 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?

For a feedback tool, it covers purpose, trigger conditions, content rules, rate limits, quota, and roadmap impact. No output schema needed. The nested context object is sufficiently described in the 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 covers all 3 parameters with descriptions, so baseline is 3. The description adds framing guidance for the message field: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which helps the agent compose feedback 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 states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and then enumerates bug, feature/data_gap, praise, which clarifies the exact purpose and distinguishes it from sibling data-retrieval tools.

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

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

Explicitly lists when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion: 'don't paste the end-user's prompt.'

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description goes beyond this by revealing the data source (CF analytics-engine), privacy guarantees (no PII), output format (pack, tool, count), and caching behavior (5min-1h depending on window) — all valuable context that annotations do not cover.

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 and well-organized, leading with the core functionality, then use cases, then technical details. Every sentence adds value with no fluff or redundancy, and the structure makes it easy to skim.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is admirably complete. It covers what the tool returns, when to use it, data source, privacy, and caching — leaving no critical gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema itself already provides a rich description of the 'window' parameter. The tool description adds an extra layer by noting that caching duration depends on the selected window, tying parameter choice to behavioral outcomes, which is a meaningful addition 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 opens with a clear, specific statement of what the tool does ('What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume'), and it explicitly differentiates this from sibling tools by focusing on AI agent call signals. The three use cases further solidify its distinct purpose.

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

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

The description provides three concrete scenarios for when to use the tool (discovering hot data sources, confirming canonical tool choice, checking alignment with other agents), giving clear context without naming alternatives. However, it doesn't explicitly say when not to use it or mention sibling tools as fallbacks, so it stops short of a 5.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive, but the description goes far beyond that by explaining internal checks (Jaccard similarity, placeholder fraction filter, fill check against CLOB depth) and the meaning of realizable_edge_pp <= 0. No contradiction with annotations.

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

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

The description is dense but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear opening summary. Every sentence adds value, and the length is appropriate for 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 outlines the response shape (opportunities[], partition_check{}, fill check output) and covers failure conditions, edge cases, and trading caveats. It is complete enough for an agent to use confidently.

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

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

Schema coverage is 100%, but the description adds significant semantic meaning: event mode with examples of slugs, topic mode with seed question examples, and the distinction between single-event and cross-event scanning. This goes well beyond the schema's basic field 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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's scope from siblings by naming an alternative (polymarket_fill_risk) for custom sizing and by detailing unique modes (event, topic).

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 instructions are provided: 'Call with NO args for a trending_scan...' and separate guidance for event vs. topic modes. It also says 'For custom sizing use polymarket_fill_risk,' which explicitly names an alternative tool, and includes a clear 'do not trade it' condition.

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 with readOnlyHint/openWorldHint/idempotentHint annotations present, the description adds substantial behavioral context: KV-level caching keyed on knobs, per-sport overround biases, placeholder-leg filtering, edge net of slippage, Kelly caps, diagnostics for empty segments, and the Fed-data reliability caveat. This goes far beyond what annotations alone 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?

The description is very long and dense, with logical structure and a front-loaded purpose, but it includes many algorithmic details (per-sport alpha values, placeholder-slug examples, Run 8 gate comparisons) that may be excess for a tool-selection task. It is appropriately organized but not 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 no output schema, the description thoroughly explains the response shape (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields, parameter effects, caching, and limitations. This is an unusually complete picture for such 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?

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds a high-level grouping ('TRADEABLE-EDGE KNOBS') and rationale for some knobs, but this does not materially extend the schema's already-rich parameter semantics.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool from siblings by describing the three model-family segments and the daily-use positioning ('what should I bet on today').

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

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

The description clearly states when to use the tool ('agents discover opportunities without paging hundreds of markets') and includes important usage nuances like the Fed-note caveat and tradeable-edge knobs. However, it does not explicitly name alternative sibling tools or state when to prefer them, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes beyond this by disclosing key behavioral details: the 60-day snapshot TTL, gaps in data due to cache-miss writes, and that decay is computed from daily closes rather than intraday. These are non-obvious implementation traits that directly affect interpretation of 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 dense but every sentence earns its place. It starts with the core purpose, then systematically covers arguments, response structure, and limitations. The use of bolded field names approximates structured documentation without sacrificing readability. 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?

Despite having no output schema, the description fully documents the response format (tracked, expired, snapshot_dates) and the meaning of each field. It also explains edge cases like gaps in snapshots and TTL limits, making the tool behavior predictable. For a non-trivial analytical tool, this exceeds completeness expectations.

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

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

The input schema already documents both parameters with descriptions and defaults, covering 100% of parameters. The description reinforces this and adds semantic meaning by explaining 'window' as a 'snapshot family' and clarifying that days controls lookback, which helps the agent understand the conceptual grouping beyond the raw schema.

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

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

The description clearly defines the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots. It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence and trend (fresh vs. old edges), using specific verbs like 'tracks' and 'answers' the question of edge age and decay.

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 on when to use the tool (to assess edge age/decay before trading) and mentions the relationship to polymarket_edges snapshots. However, it doesn't explicitly state when NOT to use it or name an alternative tool, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate that. It adds rich behavioral detail: explains the two modes (single-market and basket), how partial fills convert an arb into an unhedged directional position, and the significance of 'forced_directional_risk.' This goes well beyond the annotations and reveals the tool's safety-critical role.

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: it uses labeled mode sections (SINGLE-MARKET, BASKET) and a clear USE THIS callout. Every sentence carries operational value, and the density is justified by the tool's complexity. It could be trimmed slightly, but there is no wasted prose.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values. It lists all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, thin_legs[], forced_directional_risk, etc.), clarifies that one of market or event is required, and explains edge-case behavior. This is comprehensive 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 description coverage is 100% and the parameter descriptions in the schema are already thorough (e.g., size_usd distinguishes single-market vs basket, side enumerates options and defaults). The tool description repeats this information in narrative form without adding significant new parameter semantics. It provides useful context (e.g., size_usd as settlement notional) but largely mirrors 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 opens with a precise verb-object pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by emphasizing fill risk rather than signal generation, and explicitly frames itself as a pre-trade validation step.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This directly names the relevant sibling tools and gives a concrete threshold, offering clear context for when the tool is needed versus when it might be unnecessary.

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, and the description adds significant behavioral detail beyond that: the two safety fields (compatibility_warning cases), temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that 'pre-mapped ≠ tradeable.' This goes well beyond the minimal annotation information.

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 deliberately structured into MODES, RESPONSE, and SAFETY FIELDS, with every sentence carrying unique information. It could be trimmed slightly, but the density is justified given the tool's complexity. Front-loading the core purpose helps.

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

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

The tool has no output schema, so the description fully enumerates the response: venue leg prices, matched spread[].top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also addresses edge cases and limitations, making it complete for a complex cross-venue analysis tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the mode semantics: `topic` auto-fetches matching events via shortcuts, while explicit tickers override the mapped side. It lists all ten topic values and clarifies the roles of `kalshi_event_ticker` and `polymarket_event_slug`. This is more than the schema alone provides, so a 4 is warranted.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from siblings by focusing on cross-venue comparison, while sibling tools like polymarket_arbitrage likely target intra-venue opportunities. This is a clear, non-tautological purpose statement.

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

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

The description explains two distinct usage modes: `topic` shortcuts for pre-mapped events and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. However, it does not explicitly compare against alternative sibling tools or state when NOT to use this tool in favor of another.

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 read-only and non-destructive, and the description adds useful behavioral context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and supports both key retrieval and listing all keys. This goes beyond annotations, though it does not cover failure modes or return format.

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

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

Four sentences, each serving a distinct purpose: primary function, use case, scope, and pairing with related tools. No redundant or irrelevant information; the main behavior is front-loaded.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, when to use, scope, and related tools. It is fully complete given the tool's low complexity and the annotations already covering safety.

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 'key' and the omit-to-list behavior. The description adds concrete examples of what keys may contain (target ticker, address, research notes), which enriches the meaning beyond the schema without conflicting with it.

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

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

The description clearly states it 'retrieve[s] a value previously saved via remember, or list[s] all saved keys,' which is specific and action-oriented. It also differentiates from siblings by explicitly pairing with 'remember' and 'forget' for save/delete operations.

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

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

The description explains when to use it: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives (remember to save, forget to delete) and clarifies the scope (identifier-based), giving clear guidance on when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds key behavioral detail: mark_read:true flags returned events read, so subsequent calls only show newer ones. It also discloses that each alert carries citation_uri and the raw payload, providing state semantics beyond the structured hints.

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

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

The description is a compact four-sentence paragraph that front-loads the core purpose and adds only high-value details. No fluff; every sentence contributes meaning.

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

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

For a tool with no output schema, the description adequately describes return contents and usage patterns, including filtering and polling behavior. It could optionally mention limit defaults or pagination, but overall it gives enough context to use the tool effectively.

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

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

Schema coverage is 100% for all 5 parameters, so the schema already documents each parameter. The description adds modest value by providing an example type ('sec_8k') and elaborating on mark_read's effect on future calls, but it doesn't significantly go beyond the schema's own 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 'Pull fired events from your subscription feed,' which names the exact verb and resource. It specifically describes returned content (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

It gives clear context for when to use the tool: to pull recent alerts, with optional filters for type and time, and notes that polling is fine. It also provides an alternative HTTP endpoint for scripts, implying the tool is for interactive use, though it doesn't explicitly name sibling alternatives for comparison.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses important behavioral traits: parallel fan-out to three sources, GDELT-to-GNews fallback on rate-limit/5xx, the USPTO PatentsView sunset with soft-fail, and the structured return shape with citations. This is rich, non-obvious context that annotations alone do not 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?

The description is a single dense paragraph but is logically organized: intent, sources, fallback behavior, parameter semantics, return format, and alternative tool. It is slightly long but each clause adds necessary information; no filler exists. The front-loaded examples help orientation.

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 three parameters and no output schema, the description covers all essential aspects: accepted inputs, source behavior with fallbacks and caveats, return structure (changes[], total_changes, citation URIs), and when to prefer an alternative. It is complete enough for an agent to invoke correctly without further 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by detailing the `since` parameter's accepted formats (ISO date or relative shorthand like "7d", "30d", "3m", "1y") and recommending "30d" or "1m" for typical monitoring, which goes beyond the schema's terse description.

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

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

The description clearly states the tool's function: a change feed for a company over a specified window, aggregating SEC filings, news mentions, and patents. It uses specific verbs and examples ("What's new with X" / "latest on Y") and explicitly distinguishes itself from entity_profile, making its purpose and scope unmistakable.

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

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

The description provides clear when-to-use context via example queries and states the `since` parameter formats. It explicitly names an alternative (entity_profile) for static profile needs, giving a clear when-not-to-use directive. This exceeds the minimum for usage guidance.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description adds value by disclosing scoping ('scoped by your identifier') and persistence nuances ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It does not contradict annotations, though it could have explicitly mentioned overwrite behavior, but the idempotency hint partially covers that.

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 primary purpose. Every sentence earns its place: purpose, usage examples, and persistence details. No filler or redundancy.

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

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

For a tool with only two parameters and no output schema, the description covers usage context, persistence, scoping, and sibling relationships. It is missing potential details like error handling or overwrite semantics, but those are not critical given the tool's simplicity and the presence of annotations. Overall, it is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100% (both key and value have descriptions with examples). The description itself mentions 'key-value pair' and gives examples of values, but does not add new parameter-level detail beyond what the schema already provides. Thus, 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 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes itself from siblings like 'recall' and 'forget' by explicitly mentioning pairing. The examples of what to save (ticker, address, preference) make the purpose very concrete.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and provides specific scenarios. It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives clear when-to-use and when-not-to-use guidance relative to sibling tools.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds value by disclosing internal cascading through multiple lookup endpoints and detailing exact return fields for each type (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) plus citation URIs. This goes beyond the annotation baseline, though it doesn't cover rate limits or ambiguity resolution 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 front-loaded with example queries and a clear action statement, and the SUPPORTED TYPES structure makes it scannable. It is a bit dense—covering citation URIs, internal cascades, and alternative accepted inputs—but every element contributes practical information. It earns a 4 for being well-organized yet slightly over-packed.

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 2-param tool with no output schema, the description compensates thoroughly by specifying return values for both entity types and the internal multi-lookup behavior. It omits error/no-match handling and doesn't explain how disambiguation works, but the essential usage context is complete enough for an agent to invoke it correctly.

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

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

With 100% schema coverage, the schema already documents both parameters. The description enriches this by providing concrete examples (AAPL, 0000320193, 'ozempic') and clarifying accepted input formats for each type, as well as noting auto-disambiguation for company input. This meaningfully extends the schema descriptions.

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

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

The description opens with realistic user queries ('What's the ticker for…' / 'find the CIK for…') and then states the core function: resolve a user-spoken NAME to the canonical/official identifier other tools require. It clearly distinguishes itself from siblings by specifying the two entity types (company, drug) and what identifiers each returns, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also notes that each call replaces 2-3 manual lookups, indicating when to prefer this tool over manual steps. However, it doesn't explicitly name alternative tools or describe when NOT to use it (e.g., if you need a full entity profile instead of just an ID), so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context by explaining the internal process (probes each entity), the ranking behavior, and the return fields (score, confidence, signal density). It does not describe rate limits or error handling, but given the annotation coverage, it provides sufficient added value.

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 purpose, includes a concrete use case and output description. Every sentence contributes information, with no redundant or filler content.

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

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

Despite lacking an output schema, the description explicitly lists return fields (ranked list, score, confidence, signal density), compensating for that gap. It also explains the competitive context and entity count assumption (brand + N competitors). It could delve into validation rules or error handling, but the essential information for invocation is present.

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 does not add significant meaning beyond what's in the schema, except framing 'entities' as 'your brand + N competitors' which is already partially indicated by the schema's 'subject' note. No additional parameter semantics are provided.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs ('Compare', 'Probes', 'ranks') and a specific resource ('AI visibility'). It distinguishes itself from sibling tools by mentioning it probes each entity with ai_visibility_check and returns a ranked list, making it unique among the provided siblings.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example query. It implies the tool is for multi-entity comparison, but does not explicitly mention alternatives or say when NOT to use it. However, referencing ai_visibility_check as the probe suggests single-entity use would be handled by that 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 adds critical behavioral details beyond annotations: the composite fan-out to two APIs, graceful degradation with a 5-30s possible delay on bundlephobia's first measurement, and the sources_failed field that reports timeouts. It also clarifies that partial failures still return data. Annotations already signal read-only, idempotent, non-destructive, so this is additive.

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 for the tool's complexity, front-loading the core purpose and use-case in the first two clauses. It packs return fields, ecosystem limits, and failure behavior into a few sentences without repetition or filler.

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

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

For a composite tool with no output schema, the description is remarkably complete: it lists all key return fields, explains ecosystem scope, and details failure semantics. It even covers operational quirks like the 5-30s first measurement, making it fully self-contained for an agent to call without surprises.

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

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

The input schema already fully documents both parameters (package name with scoped-package note, version with default behavior). The description reinforces that version is optional and defaults to latest, but doesn't add new semantic information beyond the schema. Baseline 3 applies given 100% schema coverage.

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

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

The description clearly defines the tool as a composite dependency-risk check for npm packages, naming the specific data sources (deps.dev, bundlephobia) and the question it answers ('should I add this npm package'). It's distinct from sibling tools like scan_competitor_ai_presence and validate_claim, which address different domains.

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 ('whenever an agent asks "is X safe / popular / small"') and gives a concrete example (adding lodash). It also provides an exclusion rule: for non-npm ecosystems, use 'deps.dev:version' directly, which serves as an alternative.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses concrete operational details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flagging, and that each passage includes an offset for quote verification. This adds significant context about how the tool behaves.

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 not bloated; it front-loads the purpose in the first sentence, then gives usage, pairing, and implementation details. Every sentence contributes value, though it is slightly longer than the minimal necessary.

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 adequately explains the return value (top-N passages with offsets and similarity scores). It also covers input constraints (text cap, truncation), usage context, and the pairing with ask_pipeworx_grounded. This 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?

The input schema already provides 100% parameter coverage with descriptions and examples for text, query, and limit. The description adds only minor context (e.g., 'the text you already pulled') but does not meaningfully enhance the parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific input (text) and output (passages, offsets, scores). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and emphasizing 'inside' a record rather than fetching or grounding.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool (ask_pipeworx_grounded) and explains how to combine them, which serves as an alternative and integration pattern.

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

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

Beyond the annotations, the description reveals critical side effects and constraints: subscription persistence requiring OAuth, SMS phone verification and daily cap, webhook auto-disable after consecutive failures, and one-time delivery of the webhook signing secret. This is rich behavioral context that annotations alone do not 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?

The description is longer than average but every sentence carries specific operational detail. It is front-loaded with the core purpose and then organizes supporting details by subscription type and delivery channel. Some content (e.g., delivery constraints) is duplicated from the schema, preventing a perfect 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?

Despite having no output schema, the description is fully complete for a complex tool: it covers all five subscription types, required auth, all delivery channels with their caveats, rate limits, and how to consume the feed. Nothing critical appears missing.

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

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

The schema already covers parameter details with 100% coverage, so the baseline is 3. The description adds concrete semantic meaning beyond the schema, such as items:['5.02'] meaning officer change and topic:'fed' for Polymarket mispricings, making it slightly more helpful.

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 ('Create a proactive monitoring subscription to a live-data event stream') and enumerates the exact supported subscription types. This clearly distinguishes 'subscribe' from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 strong contextual usage guidance: it names requirements (Pipeworx OAuth account), explains type-specific configs, and even mentions alternative pull methods (recent_alerts or GET registry.pipeworx.io/alerts.json). It lacks an explicit 'when not to use' statement, so it stops short of a 5.

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

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

Annotations already provide readOnly, openWorld, and idempotent hints. The description adds context about the output shape (category-bucketed example questions with tool + argument shape) and the source (live catalog of thousands of tools). This goes beyond the annotations to clarify what the agent will receive, though it doesn't discuss edge cases or response size.

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

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

The description is front-loaded with example questions to quickly signal the tool's purpose, then states the core function and return format. It is somewhat long but each sentence contributes: purpose, output structure, calling modes, and usage priority. It could be tightened but remains efficient and well-structured.

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

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

There is no output schema, so the description takes on the burden of describing return values, which it does clearly: 'category-bucketed example questions ... each with the exact tool + argument shape.' It also specifies call variants and when to use, making the description complete for an onboarding tool with dynamic 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?

The input schema's description already documents the topic parameter with allowed values and default behavior ('Omit for a cross-category spread'). The tool description adds minor elaboration ('pass topic to focus') and examples, but the schema covers 100% of the parameter semantics. Baseline of 3 is appropriate, with no significant new meaning added.

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

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

The description clearly states the tool is 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies that it returns category-bucketed example questions with the exact tool and argument shape. This distinguishes it from siblings like discover_tools by positioning it as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two calling modes: no arguments for the full spread, or pass a topic to focus. This directly instructs the agent on choosing this tool over 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?

Beyond annotations, the description discloses that ownership is enforced, and that cancellation deactivates the row rather than deleting it, preserving historical events. This adds significant behavioral context and does not contradict any annotations.

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

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

Two sentences with no filler. The first sentence states the primary action, and the second adds essential behavioral context. Every word earns its place.

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

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

For a single-parameter tool with rich annotations and no output schema, the description covers key behavioral nuances (ownership, deactivation, event history) and references related tools, making it complete.

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

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

The input schema fully describes the id parameter, including its type and that it is returned by subscribe. The tool description adds no additional parameter semantics, so the baseline of 3 for high schema coverage applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource (subscription). It also adds scope by noting ownership enforcement and deactivation rather than deletion, which distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description provides clear context on ownership and data retention, implying when to use it. However, it does not explicitly name alternatives or state when-not-to-use, so it lacks full/explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: the dual-pipeline routing, percent-delta math for financial claims, the possible verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported), and the claim that it replaces 4–6 sequential calls. 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?

Although the description is long, every sentence earns its place. It starts with the most actionable information (trigger phrases and purpose), then layers in routing, output details, and efficiency benefits. The structure uses clear punctuation and examples that aid scannability without 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?

There is no output schema, so the description must fully disclose return values. It lists exact verdict types, states the actual value comes with a pipeworx:// citation, and mentions reasoning. It also covers edge cases like approximate correctness and unsupported claims. For a complex tool with routing and tolerance logic, this is complete.

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

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

Schema description coverage is 100% for both parameters. The description adds extra meaning for tolerance_pct, explaining it is a max percent deviation for approximately_correct, how to override the implied tolerance, and recommending 1–2 for hallucination detection. The claim parameter is also exemplified with concrete natural-language examples.

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

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

The description opens with explicit trigger phrases like "fact check" and "confirm or refute," then clearly states its function as "natural-language claim verification against authoritative sources." It distinguishes itself from sibling tools by focusing on producing a verdict rather than just retrieving information.

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

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

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct." It further provides a precise routing rule: financial claims go through SEC EDGAR/XBRL fast path, while any other factual claim automatically uses the grounded pipeline, effectively telling when to use this tool and how it handles different claim types.

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