Govcon Intel

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that Workers AI is free by default, that passing _apiKey triggers external Anthropic calls with direct cost to the user, and it outlines the return structure. This adds valuable behavioral context about external API interactions and cost implications.

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 well-structured sentences: first states the main action and output, second details model options and cost, third lists return fields and use cases. There is no padding, and every sentence conveys essential information without redundancy.

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

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

Given that there is no output schema, the description appropriately discloses the return shape (per-model {score, confidence, signals, raw_response} plus combined view). It also covers the default behavior, optional parameters, and typical use cases. For a read-only probing tool with 4 parameters, this is sufficient for an agent to select and invoke it correctly.

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

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

The input schema already describes all parameters clearly (100% coverage), so the baseline is 3. The description adds extra value by explaining that `models` defaults to just 'workers-ai', that `_apiKey` is only needed for Anthropic and is passed straight through (with cost implications), and clarifies the `_apiKey` format. This goes beyond the schema's structural 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 ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic'), followed by the scoring mechanism (0-100 per model). This clearly distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on LLM knowledge/visibility rather than web presence.

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

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

The description provides clear usage context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key. However, it does not explicitly mention when not to use it or compare it to sibling tools like scan_competitor_ai_presence, so it lacks the full when/when-not guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context beyond annotations: routing to 5,564 tools, filling arguments, returning stable citation URIs, and working on all tiers. It does not contradict annotations, though it could mention potential edge cases like unsupported queries.

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

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

The description is longer than average but well-structured: bolded key guidance, explicit examples, and a clear 'step up' section. Every sentence adds value, though it could be tightened to improve scannability.

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

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

The description provides comprehensive context for a complex router tool: scope, use cases, examples, alternatives, and output characteristics. Given the absence of an output schema, the description adequately explains what the agent should expect (structured answer with citations), making it complete for practical 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?

Input schema has 100% coverage with descriptions for all parameters (question plus aliases). The description reinforces with examples but does not add meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema fully documents the parameters.

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 answers questions about current or historical data via routing to thousands of sources, with a specific output format (structured answer with citations). It explicitly differentiates from sibling tools like ask_pipeworx_grounded and deep_research, making its 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?

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, lists trigger phrases and examples, and contrasts with alternatives ('step up only when needed'). It names specific sibling tools for specific scenarios, providing clear decision criteria.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds valuable context about the experimental nature: candidate routing improvements are enabled live whenever under test, and the current behavior matches ask_pipeworx exactly. It also clarifies that it is not a fallback but a full working router. This goes beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded, with the main purpose in the first sentence. Subsequent sentences explain the beta status, current state, and use guidance. The specific retirement date (2026-07-26) adds transient detail but is relevant for understanding the current state. Overall, every sentence earns its place, though it could be slightly trimmed.

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

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

For a complex universal router with no output schema, the description provides sufficient context: it explains the tool's behavior, relationship to ask_pipeworx, and that it is fully functional. It references the same response shape as ask_pipeworx, which helps the agent understand output expectations. Given the high schema coverage and annotations, this is adequately complete for the tool's complexity.

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

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

The input schema already documents all 6 parameters with 100% coverage, including aliases for 'question'. The description only states 'same arguments' as ask_pipeworx but adds no additional meaning beyond the schema. Since schema coverage is high, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description clearly identifies the tool as a beta universal router: 'identical universal router (same 5,564 tools, same arguments, same response shape) with candidate routing improvements enabled live.' This distinguishes it from ask_pipeworx by highlighting the experimental beta status, making its specific purpose unambiguous.

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

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

The description provides explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also mentions that results are compared against the stable router for merge decisions, implying that ask_pipeworx is the stable alternative. However, it does not explicitly state when NOT to use it (e.g., for production-critical tasks), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond these: it discloses the refusal mechanism with specific refusal_reason values, the return schema on success, and the extra LLM call cost. It also explains the extraction is strictly grounded in tool results, preventing fabrication. This goes far beyond the annotations and aligns with them, showing no contradiction.

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

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

The description is concise yet information-dense. It front-loads the core purpose in the first phrase, then logically transitions through routing, extraction, return shape, usage scenarios, and cost consideration. Every sentence adds value—no fluff or redundancy. It is well-structured and easy to parse.

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

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

Despite no output schema, the description thoroughly covers the tool's behavior, including the exact return structure on success and failure, the refusal reasons, and the cost implication. It gives enough context for an agent to decide when and how to invoke it, and what to expect. The tool's complexity (grounded answers with explicit refusals) is fully addressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on the question parameter beyond what the schema already states (natural language, aliases). It mentions 'fills arguments' in relation to internal tool selection, but this is about routing, not the tool's own parameters. No additional meaning is added to the input schema, so a 3 is appropriate.

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

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

The description opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by detailing the same routing but with extraction constrained to tool results, and explicitly states when to use it (fields where the answer will be quoted, cited, or acted on). The verb+resource+scope is evident, leaving no ambiguity about what this tool does.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and contrasts with 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx) and gives cost trade-offs, making it clear when to use this tool vs. the sibling.

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

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

Annotations already declare read-only and safe, but the description goes far beyond: it documents the low-confidence short-circuit status, closed/inactive market handling, illiquid wide-spread warnings, cancellation-rule risk, news fallback fields, and detailed response shapes. This provides rich behavioral context with no contradiction.

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

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

The description is long but every section earns its place with labeled classifiers, fan-out examples, response shapes, safety contracts, and resolution-rule details. It is front-loaded with purpose and then organized as a structured spec, 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 specifies the return contract (market, analysis, evidence, resolver, parent_event, news fields) and all edge-case statuses, including low-confidence matching and closed-market blocking. An agent has enough to decide when to trust and what to inspect; nothing important is missing.

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

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

Schema covers 100% of parameters, and the description adds valuable usage meaning: depth's 'quick' vs 'thorough' behavior, include_raw's response-size implications and when to enable it, and concrete input formats for the market parameter. This exceeds the baseline for full schema coverage.

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

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

The opening sentence explicitly states the tool researches a Polymarket bet by pulling relevant data in one call, with a clear verb and resource. It distinguishes itself from sibling tools like polymarket_edges or deep_research by describing the classification, fan-out, and evidence-packet pipeline.

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 scopes usage to 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z', with concrete fan-out examples. However, it does not explicitly mention when NOT to use this tool or contrast it with sibling alternatives like deep_research or polymarket_edges, so it misses full 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses specific data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, result sorting by primary metric, and return format with citation URIs. This rich behavioral context helps the agent anticipate outputs and side effects.

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

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

The description is dense but every sentence adds value: triggers, usage preference, type-specific details, output format, and efficiency gain. While longer than average, the complexity of the tool (two entity types, multiple data sources) justifies the length, and it is front-loaded with the most critical information.

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

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

Given no output schema, the description compensates by explaining the return format (paired data + citation URIs) and result sorting. It covers both entity types, constraints (2–5 items), and the tool's advantage, making it complete for selection and invocation without additional context.

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

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

Schema covers both parameters with enum and array descriptions (100% coverage). The description adds meaning beyond the schema by explaining what each entity type pulls (financial metrics for companies, adverse-event and trial counts for drugs), giving examples, and noting sort behavior. This enriches parameter understanding well above baseline.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It specifies the resource (entities) and the action (compare), and distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

Provides explicit trigger phrases ("X vs Y", "which is bigger", "rank these companies") and a strong directive to prefer this tool over sequential lookups when comparing entities. This gives the agent clear when-to-use guidance and implicitly notes when not to use it (for non-comparison lookups).

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

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

Despite readOnly/idempotent annotations, the description adds substantial behavioral detail: parallel tool routing, facet decomposition, findings packet structure (evidence, confidence, citations, gaps), and depth-specific iteration behavior. No contradictions with annotations.

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

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

The description is overly verbose and heavily repetitive. Repeated phrases (e.g., 'depth', 'ask_pipeworx', 'citation_uri') appear multiple times, making it difficult to parse. Key information is buried in a wall of text, reducing clarity.

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

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

Covers all essential aspects: purpose, alternative tools, parameter semantics, output format (findings packet with citations and gaps), and account/premium requirements. While comprehensive, the repetitive delivery detracts from completeness; a tighter structure would earn a 5.

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 detailed descriptions for both parameters. The description reinforces that broad/multi-part questions are acceptable and that depth controls parallel facets, adding context beyond the schema without redundancy concerns.

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

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

Clearly states the tool performs grounded multi-source research across structured data sources in a single call, and explicitly contrasts with ask_pipeworx for single lookups and news topics. The purpose is unambiguous and distinct from siblings.

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

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

Provides explicit when-to-use guidance: recommends ask_pipeworx for single lookups, breaking news, and non-signed-in users, while positioning deep_research for broad/multi-part structured research questions. This clearly differentiates from alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns top-N tools with full input schemas, includes curated examples, and makes results directly callable without a second lookup. This helps the agent know exactly what to expect from the response.

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 usage context, then return-value details. The list of topic areas is somewhat long but directly helps the agent judge 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?

There is no output schema, so the description carries the full burden of explaining return values. It clearly states that results include names, descriptions, and full input schemas with curated examples, and that results are ready to call directly. This fully covers the agent's need to understand what the tool returns and how to use it.

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

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

Schema description coverage is 100%, so all six properties including aliases are documented in the input schema. The description reinforces that the query should be a natural language description of the desired task but adds no semantics beyond the schema; thus the 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 opens with 'Find tools by describing the data or task' — a specific verb and resource that clearly differentiates this meta-search tool from the domain-specific sibling tools. It explicitly lists the use cases (browse, search, look up, discover) and the breadth of topic areas, 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?

The description says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives strong positive guidance and implies a contrast with directly calling a known tool, though it does not explicitly name alternatives or exclusion criteria.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral specifics: returns up to 5 recent filings with pipeworx URIs, fundamentals from LATEST 10-K sorted by period_end, patents soft-fail after the USPTO sunset in May 2025, and a GDELT→GNews fallback for news. These details reveal edge behavior and data provenance beyond the annotation safety profile.

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

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

Though long, the description is densely packed and well-structured: example intents, core promise, preference rule, source fan-out, and returned fields. Every clause adds information about coverage, format, or fallback behavior, and the structure leads the agent from purpose to usage to outputs 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?

With no output schema, the description fully explains return value structure: cik + company_name; recent_filings (up to 5 with URIs); fundamentals (field names and sort order); patents (with sunset status); news (with fallback chain); and LEI. It also covers input constraints and usage policy, making the tool fully invocable without external documentation.

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

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

Schema description coverage is 100%: both type and value have descriptive text, including ticker/CIK format and the name-not-supported instruction. The description repeats 'AAPL' and '0000320193' and the resolve_entity pointer, adding no new semantic information beyond the schema. Therefore, baseline 3 is appropriate.

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

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

The description opens with concrete example user queries and immediately states 'full cross-source profile of a US public company in ONE parallel call,' naming the exact sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It clearly distinguishes from siblings by explicitly preferring this tool over chaining single-pack lookups and by contrast with tools like compare_entities or resolve_entity.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion and alternative: 'names not supported (use resolve_entity first if you only have a name).' This is direct and actionable.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, covering safety profile. The description adds context by specifying what gets destroyed—'a previously stored memory'—and frames the action as clearing sensitive data. This goes beyond the structured fields 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 two sentences. The first states the exact action and resource; the second gives usage context and sibling pairing. No wasted words, front-loaded with the core purpose.

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

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

This is a simple 1-parameter tool with no output schema. Annotations thoroughly cover destructive and idempotent behavior. The description explains the memory metaphor, when to use it, and how it relates to remember/recall, making it fully self-contained for an agent.

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

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

Schema description coverage is 100%: the 'key' parameter is already described as 'Memory key to delete.' The description's 'by key' reinforces this but adds no new semantic detail (e.g., format, examples, or behavior when key is missing). Baseline 3 is appropriate.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb and resource. It clearly distinguishes this from sibling tools 'remember' (store) and 'recall' (retrieve) by identifying the destructive action (delete).

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names collaborating tools: 'Pair with remember and recall,' giving clear guidance on when to use this tool 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds process details (fetching the page, extracting metadata, emitting markdown) and output format (single text blob), which goes beyond the structured data and provides useful context for the agent.

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

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

The description is concise (3 sentences) and front-loaded with the core purpose. Each sentence adds value: purpose, process, and use cases. No unnecessary fluff.

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

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

For a simple tool with good annotations and schema, the description is complete. It explains what it does, how it works, output format, and use cases. However, it doesn't mention error handling or edge cases (e.g., invalid URL, max_links bounds), which would make it a 5.

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 both parameters have clear descriptions. The tool description does not add extra meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate') and resource ('a production-ready llms.txt file'). It explains the process (fetches page, extracts title/description/key links, emits standard format) and distinguishes itself from siblings by focusing on the llms.txt output file. The use cases (client indexing, own project, competitor auditing) further clarify its unique role.

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

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

The description provides clear context on when to use the tool via the 'Useful for' list, covering client work, personal projects, and competitor auditing. However, it does not explicitly state exclusions or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the types of insights returned (spending trends, recent awards, SBIR stats, top contractors), giving the agent a concrete picture of what the tool produces.

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 one tight sentence that packs purpose, examples, and return summary without any filler. Every piece of information 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?

With only one parameter, full annotations covering safety, and an output schema present, the description is complete. It explains the tool's purpose, scope, and sample output, and no further caveats are needed for this simple read-only 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 schema covers the single 'agency' parameter with 'Federal agency name'. The description adds realistic examples ('Department of Defense', 'NASA') that clarify expected input format and scope, going beyond the schema's minimal definition.

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

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

The description uses a specific verb ('Get') and resource ('contracting activity and market insights for a federal agency'), with concrete examples (DoD, NASA) and an enumeration of return content. This clearly differentiates it from sibling tools like govcon_contractor_profile and govcon_opportunity_scan.

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: it is for agency-level landscape insights, which implies when to use it. However, it does not explicitly mention alternatives or exclusions, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the return value categories and the vetting purpose, but this is largely redundant given the output schema. It does not disclose any additional behavioral traits such as data freshness, pagination, or required permissions, so the bar is met but not exceeded.

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 zero wasted words. The first sentence states the purpose and key outputs, the second gives a clear usage context. Information is front-loaded and every clause adds value.

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

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

The tool is simple (2 params, 1 required) with a complete schema and output schema. The description covers what it does, what it returns, and when to use it. No significant gaps remain given the structured data available.

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 (_apiKey and company_name). The description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate. The examples in the schema further clarify usage.

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

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

The description uses the specific verb 'vet' and clearly identifies the resource: a government contractor's registration, federal awards, and spending history. It lists concrete return values (certifications, past performance, award amounts, contract count), and the phrase 'Use when assessing vendor credibility' distinguishes it from sibling tools like govcon_agency_landscape (agency-focused) and govcon_opportunity_scan (opportunity-focused).

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

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

The description states when to use the tool: 'Use when assessing vendor credibility or experience.' This provides clear context but does not explicitly mention when not to use it or name alternative tools for different scenarios. The guidance is helpful but lacks the exclusion/alternative specificity seen in top-tier examples.

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 API key dependency and how the 'legs' behave without it, which adds value beyond the readOnlyHint and idempotentHint annotations. It does not contradict annotations and provides useful situational context, though it omits details like rate limits or pagination.

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

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

The description is concise and front-loaded with the main purpose, and each sentence contributes meaning. It could be slightly tighter, but it avoids unnecessary verbosity.

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 output schema and safety annotations, the description covers the essential context: search scope, return types, and the key-dependent behavior of certain data sources. Minor omissions like result ordering or limits prevent a higher score, but overall it is contextually adequate.

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

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

The input schema already provides full descriptions for all three parameters, so the description adds little semantic value. Worse, it mentions searching 'by keyword or agency' even though there is no agency parameter, which is misleading and undermines clarity.

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 searches open government contracts and grants with specific outputs like set-asides and SBIR solicitations. It uses a specific verb and resource, but does not explicitly distinguish itself from sibling tools like govcon_agency_landscape or govcon_contractor_profile.

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

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

The description implies usage for finding opportunities and explains the API key requirement, but it does not provide explicit when-to-use or when-not-to-use guidance against alternative tools. No exclusions or alternative tool references are given.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable context by specifying it returns the caller's subscriptions and listing the returned fields. This goes beyond the annotations without contradicting them.

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

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

The description is two succinct sentences. The first states purpose and return fields; the second gives practical usage guidance. No filler or redundant information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the key aspects: what it lists, what it returns, and when to use it. Combined with strong annotations, 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 coverage is 100% for the single parameter include_inactive, whose description already explains behavior and default. The tool description adds no additional semantic beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also enumerates the returned fields, making it distinct from sibling mutation tools like subscribe and unsubscribe.

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 two explicit use cases: reviewing current subscriptions before adding more, and finding an id to cancel. This implicitly references the subscribe and unsubscribe sibling tools, though it does not name them explicitly or state when not to use the tool.

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

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

Annotations only indicate non-read-only, non-destructive, etc. The description adds valuable disclosure: rate-limited to 5 per identifier per day, free and not counted against quota, returns a claim_token for later status checks, and that the team reads digests daily. This goes beyond annotations and sets accurate expectations for side effects and limits.

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

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

The description is front-loaded with the main action and then covers usage, exclusions, token behavior, and rate limits. It is longer than minimal but each section earns its place. A slight deduction for a motivational sentence ('signal directly affects roadmap') that is not strictly operational, but overall it remains well-structured and scannable.

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 with four optional parameters and no output schema, the description covers everything important: when to use, what to include, how to follow up with a claim_token, rate limits, and what happens after filing. The uniqueness of the tool among siblings is clear, and no critical behavioral information is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for claim_token with a concrete usage example and reinforces message quality guidance (mention Pipeworx tools/packs, avoid pasting user prompts). It also clarifies that claim_token should be used alone, which is not fully detailed in the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings by scoping exclusively to Pipeworx tools and explicitly stating feedback for other MCP servers won't be handled. The purpose is unambiguous and unique.

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

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

It provides explicit when-to-use criteria: bug, feature/data_gap, praise, and when-not-to-use: any tool not from this Pipeworx connection, with a clear instruction to file elsewhere. It also includes guidance on preferring Pipeworx tool names over end-user prompts and explains claim_token retrieval, making the usage context thorough.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds beyond these: it mentions the data source (CF analytics-engine), that no PII is included, and the caching behavior (5min-1h depending on window). It also reveals the result shape (pack, tool, count), which is valuable given no output schema.

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 a minimal sentence but every part adds distinct value: what is returned, use cases, data provenance, and caching. It is front-loaded with the primary purpose and remains well-organized.

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

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

Even without an output schema, the description tells the user exactly what is returned (top tools, top packs, total call volume), how the data is aggregated, its source, caching details, and privacy characteristics. This makes the tool self-sufficient for a simple one-parameter interface.

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

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

The schema covers the single parameter (window) fully, with a description and enum values. The description merely restates the window options without adding new semantic meaning, so the 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: 'Returns the top tools, top packs, and total call volume' over a recent window. It distinguishes itself from sibling tools like discover_tools or recent_alerts by focusing on other agents' live usage patterns.

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 explicit 'Useful for' scenarios, which gives clear guidance on when to invoke it. It does not explicitly name alternative tools that should be used instead, but the listed use cases effectively separate it from related tools.

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

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

Beyond the annotations (readOnly/idempotent), the description reveals scan scope (top ~200 markets), Jaccard threshold (≥0.30), placeholder filter (>20% returns null), and output structure. The FILL CHECK section explains how prices are validated against live CLOB depth and warns when not to trade. No contradiction with annotations.

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

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

The description is dense but every section earns its place: it covers modes, examples, filters, output schema, and fill-check caveats. The use of capitalized labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improves scannability despite overall length.

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

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

With no output schema and only two optional params, the description compensates by detailing the response fields (opportunities[], partition_check), the fill-check pricing logic, and edge cases like skipped_low_similarity and placeholder-dominated partitions. It is complete for an agent to invoke correctly without external documentation.

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

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

Although the schema already covers event and topic with descriptions, the tool description enriches them with practical guidance: examples of slugs and seed questions, accepted URL formats, and an explanation of what each mode computes. It also clarifies that calling with no arguments is a valid invocation, 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 opens with a specific verb+resource+method ('Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'), and then clearly distinguishes three invocation modes (no args, event, topic) with examples. This differentiates the tool from siblings like polymarket_edge_tracker and polymarket_fill_risk.

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

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

It explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and recommends 'event (recommended for a specific market)'. It also tells when not to trade (realizable_edge_pp ≤ 0) and directs custom sizing to polymarket_fill_risk.

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, but the description goes far beyond that: it discloses caching ('Cached 1h at the KV level'), diagnostics for empty segments ('_diagnostics so callers can see WHY a segment is empty'), the 24h-move warning, the per-leg Kelly behavior for partition arbs, and the Fed signal caveat. This exceptional transparency helps the agent predict exact behavior and edge cases.

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

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

The description is a very long, dense single paragraph with nested clauses and parentheticals, making it harder to scan than necessary. While every sentence carries substantive information, it sacrifices readability and could benefit from bullet points or clearer segmentation. It is front-loaded well (purpose first), but overall it's more verbose than ideal for an AI agent parsing quickly.

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 there is no output schema, the description thoroughly explains the response structure: top-level by_segment, fed_candidates, and _diagnostics, plus detailed fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers filtering behavior, model families, and edge cases. The response shape and gating logic are fully described, so the agent knows exactly what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains tradeable-edge knobs (min_liquidity/max_spread_pp), clarifies the min_partition_leg_kelly behavior with partition overrounds, and gives practical slippage advice ('Bump for very thin partitions; drop to 0 if you have a smarter fill model'). Not every parameter gets extra detail, but the most nuanced ones do.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and immediately distinguishes it from siblings like polymarket_arbitrage and polymarket_fill_risk by positioning it as an edge discovery tool. The phrase 'Built for "what should I bet on today"' further reinforces its purpose and target usage.

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 context for when to use the tool: 'agents discover opportunities without paging hundreds of markets' and explicitly frames it for day-to-day betting decisions. It also explains when certain segments may be empty (e.g., concentrated_longshot is 'rare-by-design') and why some filters exist. However, it doesn't explicitly name alternative tools to use instead, though sibling names are available for inference.

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/idempotent/non-destructive, and the description adds substantial behavioral detail: 60-day snapshot TTL, cache-miss gaps, decay computed on daily closes, and the tracked vs expired distinction. This goes well beyond what annotations provide.

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

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

Description is dense but well-organized with ARGS and RESPONSE labels. Every sentence earns its place by explaining behavior, limits, or return shape; no filler or redundancy.

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

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

Despite lacking an output schema, the description fully specifies the response fields and their meaning, explains data gaps and TTL, and covers parameter constraints. Highly complete for a read-only analytics tool with simple parameters.

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

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

Schema covers both parameters fully (defaults, clamps, and enum-like values). The description merely restates the defaults without adding new semantics, so the baseline 3 is appropriate.

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

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

Description states a specific analytic purpose ('how long has this edge existed and is it shrinking?') and distinguishes from sibling tools by focusing on persistence/decay rather than current edge values. The verb 'tracker' plus explicit telemetry framing makes the scope clear.

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

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

Provides clear context for when to use (evaluating edge persistence over time) and explains the trade relevance of edge age. However, no explicit exclusions or named alternatives are given, leaving some burden on the agent to infer differentiation from siblings.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds rich behavioral detail beyond that: it 'walks the ladder', returns specific fill metrics (top_of_book, vwap_fill_price, slippage_pp), identifies thin_legs, and exposes forced_directional_risk. 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 no wasted sentences. However, it is a single continuous paragraph covering multiple modes and numerous return fields, which could benefit from structural separation (e.g., bullet points for SINGLE-MARKET vs BASKET). Still, every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description must convey return values and behavior, and it does so comprehensively: return fields for both modes, interpretation of results (capture_ratio, profit_usd, verdict), risk warnings, and clear usage context relative to siblings. The 4-parameter, 0-required tool is fully specified for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (baseline 3), but the description substantially enriches parameter meaning: it explains the market vs event mode distinction, how size_usd is interpreted differently for buys vs sells vs basket mode (max spend vs target proceeds vs settlement notional), and includes defaults and clamps. This goes well beyond the schema's per-parameter 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?

Description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools (polymarket_arbitrage, polymarket_edges) by focusing on fill risk rather than opportunity detection, and further differentiates single-market vs basket modes.

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

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

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names specific alternatives and explains the failure mode (partial fills converting arb into unhedged directional position), making the when-to-use decision unambiguous.

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

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

Beyond annotations (readOnlyHint=true), the description discloses detailed behaviors: compatibility_warning conditions, temporal_alignment impact, skipped_cross_type/subtype counters, and the fact that pre-mapped topics often yield non-tradeable spreads. This goes far beyond the annotation safety hints and provides actionable context for interpreting 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a final warning. Every sentence carries specific information; no filler. The density is justified by the tool's complexity, though it could be tightened slightly.

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

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

With no output schema, the description fully explains return values (leg-by-leg prices, spread in pp, compatibility warnings, temporal alignment) and edge cases. An agent can correctly interpret results and avoid false arb signals. This is complete for the tool's complexity.

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

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

Schema covers 100% of parameters, but the description adds substantial semantic nuance: it explains the difference between topic (pre-mapped) and explicit tickers/slugs (custom overrides), lists valid topic values, and describes how modes interact. This meaningfully enhances the schema's brief property descriptions.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes and output details. It is distinct from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on cross-venue price differences.

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 the tool (when two venues price the same outcome) and provides two usage modes (topic shortcuts vs explicit event tickers). It also warns that most pre-mapped topics return compatibility warnings, effectively telling agents when NOT to trust results. However, it does not explicitly name alternative tools 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotent hint. The description adds behavior beyond annotations by explaining the two modes (retrieve vs. list all keys when key is omitted) and scoping to an identifier. It does not contradict annotations, and the added behavioral context is valuable.

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 every sentence adds value: function, usage examples, and scoping/relationships. No wasted words; concise yet informative.

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 tool with one optional parameter, no output schema, and rich annotations, the description is complete. It covers both invocation modes, scoping, and complementary siblings, giving an agent all necessary context 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 description coverage is 100%, so the parameter semantics are fully handled by the schema. The description reinforces what the key parameter does (omit to list all keys) and provides illustrative examples, but it doesn't add meaningful information beyond the schema. Per rubric, baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings like remember and forget by exactly specifying what it does, and gives concrete examples of usage (target ticker, address, research notes).

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 context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also states pairings with complementing siblings (remember to save, forget to delete) and notes scoping by identifier, which clarifies the appropriate context for using the tool.

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

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

Annotations already cover readOnly/destructive hints, so the description adds significant context about the persisted feed, the mark_read flag's effect on subsequent calls, and the availability of a public JSON endpoint. The optional state mutation via mark_read is clearly disclosed and does not contradict 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 compact and information-dense, with each sentence covering a distinct aspect: core purpose, return contents, filtering, mark_read semantics, and alternative endpoint. It is front-loaded with the primary action and contains no filler.

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

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

With all 5 parameters optional and no output schema, the description thoroughly covers the tool's behavior, including return contents, filtering, stateful mark_read, and the alternative HTTP endpoint. The unmentioned parameters (limit, unread_only) are fully documented in the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds meaningful value by giving a concrete type example ('sec_8k') and explaining mark_read's behavioral impact beyond the schema's simple 'flag returned events read'.

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,' clearly stating the action and resource. It further details the return payload (source, citation_uri, raw event payload) and filtering capabilities, distinguishing it from sibling tools like 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 usage context by noting 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards, guiding when to use this tool versus direct API access. It also explains the effect of mark_read and filters, but does not explicitly compare against sibling MCP 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, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond that: it fans out to multiple sources, has a GDELT→GNews fallback with rate-limit/5xx conditions, soft-fails USPTO due to PatentsView API sunset, and returns grouped changes 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 long but every sentence earns its place: query paraphrases for intent matching, source-fanout behavior, fallback logic, parameter format summary, return shape, and an explicit alternative tool. It is front-loaded with the most important purpose statement and contains no filler.

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

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

Given there is no output schema, the description adequately explains return structure (changes[] grouped by source, total_changes count, citation URIs) and covers source behaviors, fallbacks, and failure modes. It is complete for a tool of this complexity, with no meaningful gaps.

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

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

Schema coverage is 100% and the schema descriptions are already very detailed (e.g., `since` includes both ISO and relative formats, `value` includes ticker/CIK examples). The description mostly restates these details and adds only minor usage nuance such as 'typical monitoring', so it does not significantly elevate meaning beyond the schema.

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

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

The description opens with concrete query phrasings and then states plainly: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It precisely identifies the resource (company change feed) and the verb (returns recent changes), and explicitly contrasts itself with entity_profile, making sibling differentiation strong.

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 guidance via example questions ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also gives practical monitoring advice ('Use 30d or 1m for typical monitoring'), satisfying the usage-guidelines dimension fully.

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 idempotent and non-destructive hints; the description goes beyond by revealing that memory is scoped by user identifier, persists for authenticated users, or expires after 24 hours for anonymous sessions. It omits overwrite semantics but provides valuable behavioral context beyond annotations.

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

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

Two sentences pack purpose, usage triggers, storage mechanism, retention policy, and related tools with zero wasted words. The structure front-loads the core function and then gives operational 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 two-parameter key-value store, the description covers purpose, when to use, storage scoping, persistence, and relationships to recall/forget. No output schema exists, but return format is not complex. All necessary context 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 descriptions for key and value cover 100% of parameters, so the baseline is 3. The description adds illustrative examples of keys (e.g., 'subject_property', 'target_ticker') but does not fundamentally extend schema meaning. It provides marginal value above the schema.

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

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

Description opens with the specific verb 'Save' and resource 'data the agent will need to reuse later,' clearly distinguishing from sibling recall/forget by stating it stores data. Examples of use cases further clarify scope. The description also explicitly pairs with recall and forget, cementing its unique role.

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 trigger conditions ('when you discover something worth carrying forward') and concrete examples (resolved ticker, target address). It mentions related tools (recall, forget) but does not explicitly state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to add behavioral context beyond that. The description goes well beyond: it explains graceful degradation (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), mentions internal cascading through multiple endpoints, and discloses that unresolved identifiers are explicitly stated rather than omitted. There is 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 comprehensive but quite long—a paragraph of over 150 words. While every sentence adds value and the front-loading with usage examples is good, the density of information (especially the parenthetical about LEI/FIGI enrichment and ISIN resolution) makes it harder for an agent to parse quickly. Truncation or bullet points for supported types would improve conciseness.

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

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

Given the tool's moderate complexity (2 parameters, 1 enum, no output schema), the description covers all necessary aspects: purpose, when to use, supported types, behavior on failure, and what identifiers are returned. There is no output schema, so the description compensates by explaining the structure of results (identifier labels with source, unresolved list). This is complete for the tool's role.

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 covers both parameters with 100% description coverage (including enum choices and value format examples), so the baseline is 3. The description adds significant value by providing detailed context for each supported type: for 'company' it explains the cross-source identity spine (CIK, ticker, LEI, FIGI) and special behavior like ISIN-to-LEI resolution, and for 'drug' it specifies RxCUI and citation format. This elevates the score to 4.

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

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

The description provides a specific verb ('resolve') and resource ('entity') with clear examples of usage patterns like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes from siblings by positioning itself as the identity-resolution tool that other tools require as input, and explicitly contrasts with siblings like 'compare_entities', 'entity_profile', and 'search_within' by focusing on name-to-ID resolution.

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

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

The description explicitly states when to use this tool ('Use FIRST whenever you have a name but need an ID') and provides clear alternatives implicitly by positioning this as the prerequisite to other entity operations. It also explains supported entity types ('company' and 'drug') with detailed scope per type, and clarifies that this replaces 2-3 manual lookups, preventing redundant use.

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

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

The description discloses that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density—useful behavioral details beyond the annotations, which only declare read-only, idempotent, and non-destructive hints. It also implies multiple underlying calls, which is relevant for cost/latency expectations.

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

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

The description is three sentences, front-loaded with the core purpose, then mechanism, use case, and output. Every sentence adds value with no redundancy or unnecessary detail.

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

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

The tool has no output schema, but the description explicitly lists the return fields (score, confidence, signal density). It covers input, mechanism, and use case. It could mention that the first entity is treated as the 'subject', but that is already in the schema, so this is complete enough for a read-only tool with strong annotations.

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

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

Schema coverage is 100% with all four parameters well-described. The description adds some framing (your brand + N competitors) but does not meaningfully enhance parameter understanding beyond the schema. Baseline 3 is appropriate because the schema carries the 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 clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and surfaces the most/least recognized. It distinguishes itself from the sibling tool ai_visibility_check by explicitly stating it probes each entity with that tool, and from compare_entities by focusing specifically on AI visibility rather than generic comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and the question 'does Claude know about us as well as our competitors?' implies when to use this tool versus single-entity checks. It does not explicitly list exclusions or alternatives, but the context is sufficient for an agent to infer appropriate usage.

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?

Goes beyond annotations by disclosing partial failure behavior, bundlephobia's 5-30s first measurement, and that sources_failed will list timeouts. This enriches the readOnlyHint and idempotentHint annotations with practical runtime 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?

Every sentence contributes: purpose, usage triggers, return payload, ecosystem limits, and failure behavior. No redundant phrasing, and the most critical information 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?

Without an output schema, the description provides a detailed list of return fields (summary block, advisories, links, alternative versions) and covers failure modes. It is complete enough for an agent to understand what to expect from the call.

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

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

Schema coverage is 100% and both parameters already have clear descriptions. The description adds no further parameter-specific meaning beyond reinforcing that version defaults to latest, which is already stated in the schema.

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

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

The description opens with a specific verb and resource: 'should I add this npm package to my project' check, clearly stating it fans out to deps.dev and bundlephobia. This distinguishes it from sibling research tools by focusing on npm package evaluation.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also directs non-NPM ecosystems to 'deps.dev:version directly', providing clear exclusions and 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 several behavioral details beyond what annotations provide: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K character limit with truncation and flagging for longer inputs, and returns character offsets and similarity scores. The read-only, idempotent nature is implied by the search operation and aligns with the annotations. There is no contradiction.

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

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

The description is three sentences, each earning its place: the first states the core function, the second provides usage guidance, and the third gives technical implementation details. It is front-loaded with the most important information, uses intentional formatting (CAPS for 'INSIDE') to emphasize key constraints, and contains no filler or redundant 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 covers the essential return information (passages with offsets and similarity scores), the operational constraints (character cap, truncation), and the integration with a sibling tool. The tool is a straightforward search operation, and the description fully equips an agent to invoke it correctly and understand its 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 already provides 100% coverage for all three parameters (text, limit, query) with clear descriptions, including examples for query. The description adds minor context (e.g., 'Pass the text you already pulled' for text, 'top-N passages' for limit) but does not substantially enhance parameter understanding beyond the schema. Per the rubric, a baseline of 3 is appropriate when schema coverage is high and the description adds marginal value.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from sibling tools by emphasizing that it operates on already-fetched text, provides concrete examples (SEC 10-K, article, long tool result), and explicitly describes the return value (top-N passages with character offsets and similarity scores). This goes far beyond the tool name and title, fully clarifying what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages, provides offsets for verifying quotes). It also names a complementary tool (ask_pipeworx_grounded) and describes the workflow (fetch with the gateway, ground over relevant passages). This is clear, actionable guidance on when to use this tool 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?

Adds rich behavioral context beyond annotations: returns the new subscription id, feed is always on, SMS requires verified phone, webhook is auto-disabled after 10 failing runs, and signing secret is returned once. No contradiction with annotations (readOnly=false, idempotent=true) is present.

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

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

Though lengthy, every sentence earns its place. The description is front-loaded with purpose, then organized into supported types and delivery channels with concrete examples. No fluff or redundancy; the density 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?

Given the complex nested params and no output schema, the description fully covers return values, auth requirements, all subscription types, delivery channels, verification steps, rate limits, and webhook security. It is complete enough for an agent to invoke correctly without further research.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining type-specific semantics (e.g., items:["5.02"] = officer change) and consolidating examples for sec_8k, polymarket_edge, and fred_series, which helps the agent construct valid params beyond what the schema states.

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.' It clearly distinguishes from siblings by noting it returns a new subscription id and mentioning the always-on feed accessible via recent_alerts, separating creation from listing/cancellation.

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

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

Provides explicit usage guidance: requires a Pipeworx OAuth account, warns that anonymous + BYO cannot persist subscriptions, and details delivery alternatives (feed vs email vs sms vs webhook) with prerequisites like phone verification and the 10/day SMS cap. This tells the agent when the tool is appropriate and when it is not.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it returns category-bucketed example questions from the live catalog, includes the exact tool and argument shape for each, and accepts an optional topic parameter to focus results. It does not contradict the annotations and explains the output shape without needing an output schema.

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 but every sentence adds value: the opening examples help an agent understand natural-language queries, the core purpose is stated, and the parameter behavior is explained. It is front-loaded with an engaging list but that list could be seen as slightly delaying the main point. Still, it is not redundant or padded, earning a 4.

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

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

For a tool with only one optional parameter, no required inputs, no output schema, and strong annotations, the description is fully complete. It explains the purpose, the output structure (category-bucketed examples with tool+argument shape), the parameter behavior, and when to use it. It also names related meta-tools, providing enough context for a newly connected agent to proceed 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?

The input schema already provides 100% coverage: the `topic` parameter is fully described with its allowed values ('finance | pharma | economics | real-estate | betting | weather | government | science | news') and behavior ('Omit for a cross-category spread'). The description adds only minimal repetition of these values (with 'e.g. finance, pharma, betting') and the notion of 'focus', but no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent that wants to know what is worth asking. It specifies the verb ('suggest questions' / 'returns category-bucketed example questions') and the resource ('Pipeworx catalog of tools'), and distinguishes itself by being the 'FIRST' tool to use for discovery, with a clear scope of listing example questions with exact tool+argument shape.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes the option to call with no arguments or pass a topic. However, it does not explicitly state when not to use it (e.g., for specific data queries) or name direct alternative tools for those cases, only mentioning meta-tools as things to learn about. Thus it is strong on 'when' but lacks explicit 'when-not' and alternative naming.

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=false, destructive=false, idempotent=true), the description adds that the row is deactivated rather than deleted and that ownership is enforced. It also notes historical events remain available via recent_alerts. However, it doesn't describe error behavior (e.g., invalid id, unauthorized cancellation) or return value, which are minor gaps given the simple scope.

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

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

Three sentences, each earning its place: the core action, the ownership constraint, and the soft-delete behavior with history availability. No fluff, 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 one-parameter mutation tool with strong annotations, the description covers the essential: what it does, constraints, and side effects. The mention of recent_alerts integrates well with sibling tools. No output schema exists but the return value is predictable for a cancel operation, so no gap is significant.

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% — the only parameter 'id' is fully described as 'Subscription id (uuid) returned by subscribe.' The description does not add any additional parameter semantics, 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 action ('Cancel a subscription by id') with a specific verb and resource, and distinguishes it from siblings like subscribe (creation) and list_subscriptions (viewing). The deactivation detail further separates it from a destructive delete.

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: it's the cancellation tool, and ownership is enforced. It implies using recent_alerts for historical events after cancellation, but does not explicitly name alternatives like 'use list_subscriptions to see your subscriptions' or 'use subscribe to create a subscription.' This is clear but lacks explicit when-not/alternative guidance.

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

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

Annotations already declare readOnly/idempotent, but the description adds substantial behavioral context: the SEC EDGAR/XBRL fast path vs. the grounded pipeline, the precise meaning of could_not_verify (not evidence) vs. unsupported, the percent-delta grading, and the inclusion of pipeworx:// citations. 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-organized: front-loaded trigger phrases, then purpose, usage, internal routing, return values, and caveats. Every sentence contributes unique information, and the structure makes it easy to scan.

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

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

With no output schema, the description fully explains the return shape (verdict + actual value + citation + reasoning), the nuanced error semantics (could_not_verify vs. unsupported), and the internal routing logic. This is complete enough for correct invocation and interpretation of results.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (claim examples, tolerance_pct range and default cap). The main description adds only contextual mentions like 'exact percent-delta math' without introducing new parameter-level guidance, so it stays at the baseline for high 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 opens with concrete trigger phrases and clearly defines the tool as 'natural-language claim verification against authoritative sources'. It uses a specific verb-resource pair ('verify claims') and distinguishes itself from generic Q&A or research tools by describing the verdict-based output and the structured vs. grounded pipeline.

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' and clarifies the two kinds of claims (financial vs. other) with different routing. It also notes that it 'replaces 4–6 sequential calls', implying a preference over a multi-tool workflow. However, it does not explicitly name sibling tools as alternatives or state when not to use it.

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