Data Gov In

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context about the default Workers AI model being free, the need for a BYO Anthropic API key, and the direct billing implication, which goes beyond the structured annotations.

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

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

The description is compact and front-loaded with the core action and output. Every sentence contributes: purpose, default behavior/cost, return format, and use cases. No wasted words.

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

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

Given the tool's moderate complexity and the lack of an output schema, the description covers all essential aspects: what it probes, scoring range, default vs. optional models, return structure, and practical use cases. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaning by clarifying which model is default (workers-ai) and how _apiKey enables Anthropic probing, which supplements the schema's plain descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It uses a specific verb ('Probe') and mentions distinct outputs, distinguishing it from sibling tools like ask_pipeworx or compare_entities.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes the default model option. It stops short of explicitly naming alternative tools or exclusion criteria, so it doesn't fully earn a 5, but it does convey when to use it.

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

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

The description discloses the tool's routing behavior, argument-filling behavior, and the fact that it returns stable pipeworx:// citation URIs, which goes beyond the readOnly/openWorld/idempotent annotations. It does not mention potential latency, rate limits, or failure modes, but for a read-only router tool the disclosed behavior is substantial.

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 information-dense and front-loaded with the most important guidance, but it becomes rambling and somewhat garbled in the middle ('entity-dense or simply-put answer of top response with highest certainty', 'clear-cut fork'). Several alternative-routing clauses are packed into a long run-on passage, making it harder to parse than necessary.

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

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

Given the tool's complexity, the lack of an output schema, and the broad scope, the description covers the essential context: what it does, when to prefer it, when to use alternatives, and what the return contains (structured answer + citation URIs). It could mention limitations or edge cases, but what an agent needs to invoke it correctly is mostly 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 description coverage is 100%: every parameter, including aliases for 'question', is described in the input schema. The description adds no additional parameter-level semantics, but it does not need to; the baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description clearly states the tool's verb and resource: it routes a natural-language question to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns a structured answer with citation URIs. It also distinguishes itself from web search and several siblings, making its role immediately identifiable.

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', 'START HERE for most questions'), lists trigger phrases and concrete examples, and names specific alternatives for specific cases (ai_visibility_check, ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, standard web search). This is strong routing guidance.

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

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

Beyond the read-only/idempotent annotations, it discloses that candidate routing improvements may be enabled live, that no candidate is currently active, and that the tool is a full working router with no fallback despite being experimental. This is precisely the kind of behavior an agent cannot infer from annotations alone.

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

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

The description is longer than average, but each sentence earns its place: current status, why it exists, how to use it, and what changes. The first sentence front-loads the core identity and equivalence, so an agent gets the key information immediately.

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 tool, the description covers current state, expected behavior, output equivalence, and the experimental caveat. It even addresses the likely failure assumption with 'Falls back to nothing — this IS a full working router', making the calling context complete despite no output schema.

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

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

The input schema already documents all six parameters and the question field explains that aliases are accepted, so the description adds little parameter-specific meaning. The 'same arguments as ask_pipeworx' statement is helpful but does not deepen parameter semantics beyond the 100% schema coverage.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' and specifies the same 5,798 tools, arguments, and response shape, so an agent immediately knows this is a routing tool, not a data source. It differentiates itself from the stable sibling by being the experimental edge with candidate routing improvements.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and contrasts it with the stable router whose results are compared for merge decisions. This gives an agent a clear selection rule among at least ask_pipeworx and ask_pipeworx_beta.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: it refuses rather than invents when data does not directly answer, returns specific refusal_reason values, extracts only from tool result content, and costs an extra LLM call. These details materially affect invocation expectations and result interpretation. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, output contract, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the most decision-relevant information and remains readable despite its length.

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

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

Despite having no output schema, the description fully specifies both success and refusal return shapes, including the refusal_reason enum. It also covers when to use, when not to use, and the cost trade-off. For a grounded-answer tool with a single required parameter, nothing essential 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% and the input schema fully documents the question parameter and its aliases. The description adds no new parameter-level meaning, but none is needed because the schema already carries the semantic load. Baseline 3 appropriately reflects this balance.

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, differentiating purpose: 'hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the resource (Pipeworx), the verb (answer), and the distinguishing behavior (extracts using only tool result). It also explicitly contrasts with sibling ask_pipeworx, making the tool's unique role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also provides a clear exclusion with an alternative: 'prefer ask_pipeworx for casual lookups.' This is direct, actionable routing.

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 goes far beyond these by documenting resolver contract behavior (market_match_confidence, alternative matches), short-circuit statuses (low_confidence_match, market_closed_or_inactive), parent_event extraction, wide-spread illiquidity flags, and cancellation-rule parsing. It discloses critical behavioral nuances such as blocking paths and rule-based loss risks, with no contradiction to 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 structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Each section provides operational value an agent needs, covering edge cases and response handling. The fan-out examples are illustrative rather than padding. Very dense but organized for easy scanning.

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

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

Given the tool's complexity (multiple classifiers, fan-out behaviors, dynamic responses), no output schema, and only 3 parameters, the description is exceptionally complete. It documents response shapes (market, analysis, evidence), resolver contract fields, parent_event structure, news fallback flags, safety short-circuits, closed-market status, and cancellation-rule risk. It provides enough context to use the tool correctly across many scenarios.

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

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

The input schema has 100% coverage with detailed property descriptions for market, depth, and include_raw, including tradeoffs like response size and recommended false. The description adds no new parameter-level semantics; it simply echoes the market input format in examples and mentions include_raw behavior that is already fully documented in the schema. Thus it meets the baseline for high schema coverage but does not go beyond.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This provides a specific verb ('research'), resource ('Polymarket bet'), and scope (market query). However, it does not explicitly differentiate from sibling tools like polymarket_edges or validate_claim, which overlap in purposes like detecting edges.

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

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

The description includes explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples for various bet categories (BTC, Fed, Hormuz, Yankees, etc.). It lacks explicit when-not-to-use guidance or alternative tool recommendations, but the usage context is clear and actionable.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it pulls specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. It also notes it replaces 8–15 sequential lookups, revealing performance characteristics.

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

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

The description is slightly long but front-loaded with practical examples and every sentence contributes unique value. It avoids repetition and uses clear formatting with trigger phrases, type specifics, and result behavior.

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

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

Despite having no output schema, the description explains return format (paired data + citation URIs) and sorting order. Combined with the rich parameter details and sibling differentiation, it gives the agent a complete picture of the tool's behavior, including data sources and edge-case handling (off-calendar fiscal years).

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 both parameters with descriptions (100% coverage), but the description enriches them: type='company' triggers pulling specific financial fields from SEC EDGAR, while type='drug' pulls adverse-event and trial counts. This adds meaning beyond the schema's basic enum and value 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 performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific examples of trigger phrases. It distinguishes itself from siblings by noting it should be preferred over sequential single-pack lookups for comparisons.

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

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

Explicit usage guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete query examples and defines the scope (2–5 entities), making it clear when to use this tool versus alternative approaches.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: it never invented answers (explicit gaps[]), discloses latency ('Expect 15-60s... up to ~90s'), guarantees citation fetchability ('present only when the source emits one that resources/read can actually serve'), and explains semantic excerpting instead of head-truncation. 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 (~250 words) but dense — every sentence carries distinct information (auth, routing, mechanism, return shape, depth variants, latency, citation semantics, excerpting) and the most critical facts (account requirement, fallback tool) are front-loaded. Minor redundancy: the prose re-describes depth behaviors that the schema already documents.

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 carries the return-value burden: findings packet contents, gaps[], contradictions[], hop field, and citation_uri are all specified. Combined with account prerequisites, latency, alternatives, and depth semantics, nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes further: it ties the depth enum to the paid plan ('depth:"thorough" needs a paid plan'), attaches latency expectations to the depth levels, and notes that 'standard' and 'thorough' return contradictions[]. The question parameter is given usage context ('Broad/multi-part is fine — decomposition is the point').

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?

Names a specific operation — 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' — and explicitly disambiguates from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx instead.' The one-call parallel decomposition and findings-packet return make its scope unmistakable.

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

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

Provides explicit when/when-not rules and names the alternative: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead,' plus the eligibility gate 'ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx instead — it works on every tier.' No inference is required to route to this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds key behavioral context: it returns tool metadata (names, descriptions, full input schemas) rather than actual data, and each result is 'ready to call directly, no second schema lookup needed'. This goes beyond annotations by explaining the output nature, though it omits details like ranking criteria or error behavior.

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

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

The description is appropriately sized for a meta-tool. It front-loads 'Find tools by describing the data or task', then provides a relevant domain list, return-behavior details, and strategic usage advice. Every sentence contributes value, and the list of domains is useful, not padding. Structure is clear 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?

Despite having no output schema, the description fully explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also covers the default/max limit via the 'limit' parameter in schema. Given the tool's meta-purpose, the description is complete: it tells the agent what this discovery tool returns and when to invoke it.

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

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

Schema description coverage is 100% – all 6 parameters (query, q, task, search, description, limit) are described with aliases and examples. The description text reinforces that the query is a natural-language description, but adds no additional semantic information beyond what the schema already provides. 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 'Find tools by describing the data or task' – a clear verb+resource+method. It explicitly lists the domains covered (SEC filings, FDA, FRED, etc.) and distinguishes itself from siblings as the discovery/meta-tool. The phrase 'Call this FIRST...' further separates it from domain-specific tools.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and strategic instruction 'Call this FIRST when you have many tools available...'. This is strong usage direction, clarifying when to use discovery vs. directly calling a specific 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 cover read-only/idempotent/destructive traits, but the description adds exceptional behavioral detail: parallel fan-out across sources, USPTO API sunset soft-fail, GDELT→GNews fallback, sorted fundamentals, and the contract that empty sections are real 'no data' rather than bugs. This goes well beyond the structured hints.

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

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

The description is long but dense and front-loaded with purpose and examples; every sentence covers a distinct facet (inputs, source fan-out, return fields, failure semantics). No filler or repetition of the schema verbatim.

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 high complexity, no output schema, and only two simple params, the description carries the full context burden and succeeds: it enumerates return sections, source failures, URI formats, sort order, input resolution behavior, and scope limits. An agent can call it correctly without guessing.

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 already 100%, but the description adds meaning: value accepts a ticker, zero-padded CIK, or company name; names resolve via SEC EDGAR; both type enum values behave identically; and private companies return resolved:false rather than erroring. This materially enriches 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 user prompts and states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, so an agent can see this is the holistic tool versus narrower lookup alternatives.

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

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

It explicitly says to ALWAYS PREFER this tool when the user asks for a holistic view, and it clarifies expected empty sections ('that is expected, not a failure') and private-company behavior. It also states both type values are interchangeable, removing a common decision point.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate them. It adds useful context by specifying what gets deleted (previously stored memories) and a real-world scenario (clearing sensitive data). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action, and provides usage context without any wasteful words. Every sentence earns its place.

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

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

This is a simple one-parameter tool with strong annotations and schema coverage. The description covers purpose, usage scenarios, and related tools, making it adequately complete for an AI agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the key parameter described as 'Memory key to delete.' The description reiterates 'by key' but adds no additional semantic detail beyond the schema, 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 states 'Delete a previously stored memory by key,' which is a specific verb (delete), resource (memory), and method (by key). This clearly distinguishes it from sibling tools remember and recall, making its 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?

It provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but lacks explicit when-not-to-use guidance, so it falls just short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the operational pipeline: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output as a single text blob for site-root placement. No contradiction with annotations exists.

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 primary action. Every sentence earns its place: main function, process, output, and use cases. No redundant or vague wording.

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 tool with no output schema, the description covers purpose, process, output format, and use cases adequately. Minor omissions like URL accessibility or error handling are not critical given the tool's simplicity.

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

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

The schema provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description adds no extra parameter-specific detail beyond what the schema already states, though it does mention extracting title/description/key links, which indirectly relates to how the url is used.

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

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

The description states the exact action: 'Generate a production-ready llms.txt file for any URL' and explains its purpose for AI crawlers. This specific verb+resource clearly distinguishes it from sibling tools like ai_visibility_check, which focus on checking visibility rather than generating the file.

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 'Useful for:' section listing three specific use cases (client site indexing, self-project drafting, competitor auditing). It gives strong context on when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature. The description adds context about the caller-scoped list and the return fields, but does not disclose additional behavioral traits like pagination or permission requirements. This is adequate but not rich.

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

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

Two sentences, front-loaded with the primary purpose and return fields, followed by practical use cases. Every sentence contributes value, with no redundancy or fluff.

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

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

For a simple read-only list tool with no output schema, the description is complete: it states what it does, what it returns, and when to use it. The sibling context reinforces its role relative to subscribe/unsubscribe, and annotations cover safety.

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

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

Schema coverage is 100% for the single optional parameter. The description's mention of 'active subscriptions' aligns with the schema's default for include_inactive, but does not add meaningful detail beyond what the schema already provides. 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 lists the caller's active subscriptions, a specific resource, and enumerates the returned fields. It distinguishes itself from siblings like subscribe and unsubscribe by focusing on listing rather than creating or canceling.

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: review monitoring before adding more subscriptions or find an id to cancel. It implies the alternatives (subscribe/unsubscribe) but does not directly name them or give when-not-to-use conditions, so it falls short of a perfect score.

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

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

The description goes well beyond the annotations (all false) by disclosing behavior: filing returns a claim_token, how to later query resolution status, a rate limit of 5 per identifier per day, and that it doesn't count against quota. It also notes the team reads digests daily and that signal affects roadmap. This is rich, useful context with no annotation 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 dense but every sentence carries a distinct purpose: purpose, when to use, exclusion, content guidance, claim-token workflow, and rate limit. It is front-loaded and structured, though the middle section is a bit long with multiple clauses. No wasted words.

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

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

With no output schema, the description fully covers return behavior (claim_token and its later use), rate limits, and scope boundaries. It also handles the nested context object by telling users what to include (tool/pack/vertical) and provides type-enum guidance. The tool is a simple feedback form, and this description 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?

Input schema coverage is 100% (baseline 3), but the description adds meaning: it explains the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:...}) to read whether it was fixed'), and instructs users to describe issues in terms of Pipeworx tools/packs, not the end-user prompt. These details enrich the schema's bare parameter definitions.

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

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

The description opens with a clear, specific verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback categories (bug, feature/data_gap, praise) and is clearly distinct from siblings like ask_pipeworx or discover_tools, which serve different functions.

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 'Use when' conditions list every feedback type: wrong/stale data (bug), tool missing from catalog (feature/data_gap), and positive experience (praise). It also gives a strong exclusion: if the tool came from a different MCP server, file it there instead. This makes it unambiguous when to invoke this tool and when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it discloses the data source (CF analytics-engine), privacy implications ('no PII'), output granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). No contradictions.

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

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

The description is concise yet complete: a one-sentence hook, a summary of outputs, three bulleted use cases, and two sentences on data provenance/caching. Every sentence adds unique value, and the structure is front-loaded with the core function.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is remarkably complete. It explains the return contents (top tools, packs, call volume), data origin, privacy characteristics, caching, and provides concrete usage scenarios—leaving no significant gaps.

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

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

Schema description coverage is 100%, including the enum values and their semantic tradeoff ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds extra parameter-related context by linking window choice to cache freshness ('Cached 5min-1h depending on window'), going beyond the schema.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It also specifies the resource (Pipeworx) and provides concrete use cases, distinguishing it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregate usage trends.

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

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

The description explicitly lists three 'Useful for' scenarios, giving clear guidance on when to invoke the tool. However, it does not explicitly mention alternatives or exclusions (e.g., when to use discover_tools instead), so it stops short of the full when/when-not/alternatives 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?

The description discloses extensive behavioral details beyond the annotations: the threshold for signals (deviations >3pp), the semantic anchor (Jaccard ≥0.30), the partition filter (placeholder slugs, >20% fraction), and the fill check using live CLOB depth. It also warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade... do not trade it.' This adds transparency well beyond readOnly/idempotent hints.

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

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

The description is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. While it is long, every sentence provides necessary context for a complex tool. There is no redundancy; it efficiently packs mode explanations, examples, and edge-case behaviors into a cohesive block.

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 explains the response structure: opportunities[] with fields, partition_check object, and fill check details. It also covers default behavior (no args), edge cases (low similarity, placeholder filters), and actionable guidance (don't trade if realizable edge ≤ 0). The description 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?

Though the schema fully covers both parameters, the description adds significant semantic value: examples of slugs and seed questions, behavior for each parameter, and the no-arg default. It explains what the tool does with the 'event' and 'topic' values, including walking child markets, checking ordering, and running partition checks. This goes far beyond the schema's brief descriptions.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage), the action (find), and the method (monotonicity/partition-sum checks). It also differentiates from sibling tools by explicitly referencing polymarket_fill_risk for sizing.

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 for each mode: no-arg for trending_scan, 'event' for single-market scan with slugs, and 'topic' for cross-event scanning. It recommends 'event' for a specific market and explains when each is appropriate. It also points to polymarket_fill_risk for custom sizing, effectively distinguishing from an alternative.

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

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

Going well beyond the readOnly/idempotent annotations, the description discloses substantial behavioral details: caching at the KV level for 1 hour keyed on knobs, why Fed bets are excluded from ranking (unreliable signal), the gate relaxation for concentrated_longshot from prior runs, and the design quirk that partition arbs always return kelly_fraction_half=0 at the parent level. It also warns that a 24h move may already price in the edge. This is a rich, transparent behavioral account.

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 highly structured: it breaks the content into model families, opportunity components, response segments, and knobs. Every section serves a purpose for understanding the tool's behavior and output. It is dense but not wasteful; given the tool's complexity, the length is justified. A perfect score would require slightly tighter prose without sacrificing 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?

This is a complex tool with no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: it lists the three segments under by_segment, the fed_candidates/fed_note exclusion, and the _diagnostics with funnel counters to explain empty segments. It also enumerates the fields carried by every opportunity (edge_pp_net, kelly_fraction, liquidity, etc.). 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?

The input schema has 100% parameter coverage, so the baseline is 3. The description does add some context by labeling min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS' and explaining how min_partition_leg_kelly interacts with partitions, but this largely repeats what the schema already states. The added value is minor, not enough to push 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 opens with a specific verb+resource+goal: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings like polymarket_arbitrage or polymarket_edge_tracker by detailing the model families and response segments. The purpose is unambiguous and directly actionable for an agent.

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: it is 'Built for "what should I bet on today"' and helps agents 'discover opportunities without paging hundreds of markets.' It explains the tradeable-edge knobs (min_liquidity, max_spread_pp) and when to adjust them, but does not explicitly name alternative tools or state when not to use this one. No exclusions are given, so it earns a 4 rather than a 5.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral detail: data source from daily snapshots, response structure, snapshot gap semantics, and the nuance that edge_pp_net is signed by trade direction. It also clarifies that decay numbers come from daily closes, not intraday, and explains TTL bounds—all 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?

The description is organized into Args, RESPONSE, and LIMITS sections, front-loaded with purpose. It is dense but every sentence adds operational value, such as the interpretation of median lifespan as a competition clock and the note about snapshot gaps. Slightly long, but justified by the complexity.

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

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

With no output schema, the description fully specifies the response shape: tracked[], expired[], snapshot_dates[], including field-level semantics (trend values, decay_pp_per_day, lifespan_days). It also covers edge cases like snapshot gaps and data history bounds, making it highly complete for an agent to invoke and interpret results.

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

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

The input schema already documents both parameters with descriptions, defaults, and clamps (100% coverage). The tool description only restates the default values ('default 14, max 30' and 'default "1wk"') without adding new semantic meaning or context, so it remains at the baseline.

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

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

The description clearly states its function: 'Edge persistence and decay telemetry' and the exact question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling tools like polymarket_edges, which presumably provides current edge data, by focusing on historical persistence and decay.

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

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

The description establishes a clear use case ('Answers ... is it shrinking?') and provides practical limits (60-day TTL, snapshot gaps). It does not explicitly name alternatives or when-not-to-use, but the context is sufficient for an agent to infer when to select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds deep behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict), interprets size_usd differently by mode, and warns about partial-fill risk converting an arb into an unhedged position. No contradictions with annotations.

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

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

The description is long but well-structured: it opens with the core purpose, then breaks into SINGLE-MARKET and BASKET sections with clear parameter mappings and output lists. Every sentence adds useful information, though it could benefit from bullet points. It's appropriately detailed for a complex tool.

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

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

Given no output schema and 4 params with no required ones, the description fully compensates: it enumerates return fields for both modes, explains the verdict values, identifies risky legs, and provides context on when theoretical edge is not capturable. It's complete enough for an agent to understand tool behavior and output before invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond schema by explaining how size_usd maps to 'max spend on buys, target proceeds on sells' and basket 'settlement notional S (shares per leg; each share pays $1)', plus clarifies automatic side detection in basket mode. These are semantic clarifications the schema alone doesn't fully 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 leads with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explaining it's a pre-trade risk check for those signals.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and describes two modes (single-market vs basket), which helps the agent choose between them.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description does not contradict them. It goes far beyond the annotations by disclosing pairing_unverified, the gross-of-fees nature of every spread, the never-paired 'unknown' legs, and the possibility that compatibility_codes can be non-empty even when matched_pairs > 0.

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 definition is long but well-organized with labeled sections and front-loaded core content. Some redundancy exists, such as repeated warnings that pre-mapped ≠ tradeable, but the density is largely justified by the many edge-case safety codes and interpretation rules an agent must grasp before calling the tool.

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

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

With no output schema, the description compensates thoroughly by enumerating response fields, safety codes, per-pair flags, skipped counters, fee treatment, and temporal_alignment semantics including what null means. An agent has enough information to call either mode correctly and interpret the returned data safely.

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

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

The schema already provides full coverage of all three parameters, leaving a baseline of 3. The description adds meaningful mode-level semantics: topic auto-fetches matching events on both venues, explicit ticker/slug overrides the topic-mapped side, and both modes run the same token-overlap matcher with identical disclosures.

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 states a specific computation: cross-venue spread between Kalshi and Polymarket for the same resolving question. It adds distinguishing semantics by explaining that the spread is meaningful only when bet shapes are equivalent, and the 'cross-venue' scope separates it from same-venue arbitrage/edge tools.

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

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

The description clearly explains when to use the two invocation modes: topic shortcuts for pre-mapped macro events, and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning. However, it never explicitly names alternatives among sibling tools like polymarket_arbitrage, so routing guidance is implicit rather than direct.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds important behavioral context beyond these: the conditional dual-mode behavior (retrieve vs. list when key is omitted) and the scoping mechanism ('Scoped to your identifier'). This supplements 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 three sentences, each serving a distinct purpose: defining the operation, giving the usage context, and explaining scoping. It is front-loaded with the core action and avoids fluff or redundancy. 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?

Despite having no output schema, the description adequately covers the tool's behavior, scoping, and relationship to siblings. It explains both modes (retrieve by key, list by omission) and provides sufficient context for an agent to correctly select and invoke the tool. The tool is simple, and the description leaves no critical 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?

The input schema provides 100% coverage of the 'key' parameter, including its optionality and the list-all behavior when omitted. The description adds value by giving real-world examples of what keys might contain ('the user's target ticker, an address, prior research notes') and clarifying that the value was 'previously saved via remember,' which enriches the semantics beyond the schema's mechanical 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 clearly states both functions: retrieving a saved value by key and listing all keys when the key is omitted. It uses specific verbs ('retrieve', 'list') and explicitly ties the tool to its sibling tools ('remember' and 'forget'), distinguishing it from other tools in the list.

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 the tool: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also implicitly contrasts with 'remember' (save) and 'forget' (delete) by saying 'Pair with remember to save, forget to delete,' giving clear guidance on alternative tools for different operations.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral details beyond that: the mark_read flag's side effect on future calls ('so the next call only shows newer ones') and the return payload composition ('each carries source, citation_uri, and the raw event payload'). It does not contradict any annotation and provides meaningful context.

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

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

The description is three sentences long and front-loads the core purpose. Every sentence adds value: purpose, return format/filter/mark_read behavior, and polling/alternative endpoint note. No filler or repetition.

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

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

With no output schema, the description compensates by explaining the return payload at a high level. It covers usage patterns (filters, mark_read), polling suitability, and an external reference for integration. The tool is simple and the description is complete for the given 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?

The input schema already documents all 5 parameters with 100% coverage, so the baseline is 3. The description adds value by giving a concrete filter example ('e.g. "sec_8k"'), clarifying the 'since' parameter as an ISO timestamp, and explaining the consequence of mark_read in operational terms. This goes slightly beyond the repetitive schema descriptions.

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

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

The description uses a specific verb+resource construction ('Pull fired events from your subscription feed') and clearly identifies the tool's output ('Returns the most recent alerts the evaluator has written to your persisted feed'). It distinguishes itself from siblings like 'recent_changes' by explicitly focusing on alert events from the subscription feed.

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 that this tool is suitable for polling ('Polls work fine') and provides an explicit alternative for scripts/dashboards via a direct HTTP endpoint ('the same feed is also at GET registry.pipeworx.io/alerts.json'). It does not explicitly state when not to use the tool, but the context is sufficient.

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

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

The description goes well beyond the readOnly/idempotent/not-destructive annotations by disclosing data source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), specific fallback conditions (rate-limited or 5xx), and the USPTO PatentsView sunset causing soft-fail. It also describes the return structure (changes[] grouped by source, total_changes, citation URIs), adding valuable behavioral context.

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

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

The description is dense but information-dense; every sentence contributes meaning, including source behavior, fallbacks, parameter syntax, and return format. It is slightly longer than ideal but appropriate for a multi-source aggregator with important caveats.

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 shape, grouped sources, count, and citation URIs. It also covers parameter formats, source fallbacks, and a clear alternative, making it complete enough for correct selection and invocation.

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

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

Input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds minor clarifications like 'Use 30d or 1m for typical monitoring' and ticker/CIK examples, but these mostly restate schema info rather than introduce new 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 is a 'change feed for a company' covering filings, news, and patents, with example queries ('What's new with X', 'updates on Acme'). It distinguishes itself from sibling entity_profile by explicitly directing users to that tool for static profiles.

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 contexts through natural language examples and names an alternative ('Use entity_profile instead when you want the static profile... regardless of window'). This gives clear guidance for selecting between recent_changes and 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?

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds valuable context beyond these: memory is scoped by the agent's identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. This is useful behavioral disclosure, though it doesn't explicitly mention overwrite semantics for duplicate keys, which is a minor gap given idempotent hints.

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

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

The description is concise yet information-dense, front-loading the main action ('Save data the agent will need to reuse later') and following with specific use cases, storage mechanics, persistence rules, and sibling tool pairings. Every sentence earns its place, with no redundant filler or repetition of the title.

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

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

For a simple write tool with two string parameters and no output schema, the description is remarkably complete. It covers the tool's purpose, when to use it, storage semantics (key-value, scoped), persistence behavior (auth vs. anonymous), and how it relates to recall and forget. Nothing essential is missing for an agent to successfully select and invoke this tool.

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

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

The input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds no additional parameter-level semantics beyond what the schema already provides—both 'key' and 'value' are fully explained with examples in the schema, and the description's examples (ticker, address, preferences) mirror those in the schema without adding new format or constraint information.

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 saves data for later reuse, using the specific verb 'Save' and resource 'key-value pair'. It explicitly distinguishes itself from sibling tools by naming 'recall' for retrieval and 'forget' for deletion, making its unique role in the memory trio 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 guidance: 'Use when you discover something worth carrying forward' and lists concrete examples (resolved ticker, target address, user preference, research subject). It also clarifies when to use alternatives by instructing to pair with 'recall' to retrieve and 'forget' to delete, establishing a clear decision framework.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive, so the bar is lower; the description still adds substantial behavior beyond that: cascading through multiple lookup endpoints, graceful degradation if GLEIF or OpenFIGI is unavailable, returning figi_candidates on ambiguity rather than asserting, and explicitly reporting unresolved identifiers. No annotation contradiction exists.

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

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

The description is appropriately front-loaded with purpose and 'Use FIRST,' but the SUPPORTED TYPES section is dense, uses long nested parentheticals, and repeats the name-to-ID idea. The content is valuable, but readability would improve by separating the two entity types and trimming redundant rationale.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so well: CIK, ticker, company_name, LEI with ownership, FIGI, RxCUI/ingredient/brand/citation, figi_candidates for ambiguity, and unresolved identifiers. Graceful degradation and source labelling are also covered, leaving no major gap for selection or invocation.

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

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

Schema coverage is 100%, but the description adds critical meaning beyond the schema: it documents ISIN as an accepted company input, instructs callers to pass the bare entity name rather than the full noun phrase, and explains why trailing security-class words cause FIGI lookup failure. This is exactly the kind of semantic guidance a schema alone rarely provides.

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

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

The description states a clear verb and resource: resolve user-spoken names to canonical/official identifiers other tools require. It opens with concrete query examples and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling lookup/profile tools. It also enumerates supported types, making its scope immediately recognizable.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' and explains when 'company' vs 'drug' applies, including acceptable input forms. It does not name specific sibling tools to avoid in favor of this one, so exclusions are implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: pagination, per-field filtering, field projection, sorting, and the exact format/location of resourceId. It stops short of covering error handling or response format, but the annotation coverage lowers the burden.

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?

Five sentences, all front-loaded with the core action. No filler; the example resource and field list earn their place. The structure moves from general capability to specific resourceId guidance to an actionable pointer to resource_meta.

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 7 parameters, nested objects, and no output schema, the description covers purpose, capabilities, example usage, and relationship to a sibling tool. It does not explicitly describe the return format, but the read-only annotations and 'fetch records' phrasing make the intent clear. Overall, highly complete for a data-fetching tool.

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

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

Schema description coverage is 100% for all 7 parameters, so baseline is 3. The description goes beyond by providing a concrete example resourceId and listing its fields (state, district, market, commodity, etc.), which helps the agent understand possible filter/sort values. It also directs to resource_meta for field discovery.

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: 'Fetch records from any India Open Government Data (data.gov.in) resource by its resourceId.' It clearly distinguishes this tool from siblings like resource_meta by focusing on record retrieval, not metadata.

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

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

It explicitly instructs when to use an alternative: 'Use resource_meta first if you do not know a resource's field ids.' This gives a clear precondition and names the sibling tool, providing both when-to-use and when-to-defer 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 cover safety (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral context beyond annotations by specifying the return contents (metadata fields, field name/id/type) and the purpose of the resourceId. It does not contradict annotations.

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

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

Two sentences, leading with the action and resource, then providing the key use case. No filler or redundant content; every sentence earns its place.

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

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

Given the tool's simplicity, the description fully explains the return structure (title, org, sector, last-updated, field list with name/id/type) and its purpose. Missing details like error handling or rate limits are minor for a read-only metadata fetch, especially 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 covers 100% of parameters with descriptions and examples, so the baseline is 3. The description reinforces that resourceId is a UUID from the dataset page, which adds slight context, but no new parameter semantics beyond what the schema already provides.

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: 'Fetch the schema/metadata for a data.gov.in resource by resourceId'. It lists the specific contents (title, org, sector, last-updated, fields), and explicitly distinguishes it from the sibling tool resource_data by saying 'before calling resource_data'.

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

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

Provides direct usage guidance: 'Use this to discover the filterable/sortable field ids before calling resource_data.' This tells the agent when to use this tool and how it relates to the likely alternative (resource_data), including the sequential dependency.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the probe-and-rank behavior and the return structure (ranked list with score, confidence, signal density). No annotation 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?

Two sentences, front-loaded with purpose, then use case, then output summary. Every sentence earns its place with zero waste.

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

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

Despite no output schema, the description summarizes the return format. Parameters are fully documented in schema, annotations cover safety, and the behavioral flow is clear. For a read-only, idempotent tool, 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%, so baseline is 3. The description adds meaningful semantics beyond schema, notably that the first entity is treated as the 'subject' and the rest as competitors, and that models are probed. This clarifies the role of the entities array.

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

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

The description clearly states a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side'. It also distinguishes from siblings by noting it probes with ai_visibility_check and ranks results, making it distinct from the single-entity ai_visibility_check and generic compare_entities.

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 a concrete use case: 'competitive AI-marketing audits' with an example question. It implies when to use it (multi-entity comparison) but does not explicitly say when not to use alternatives. The reference to probing with ai_visibility_check implicitly contrasts with that sibling 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 mark readOnlyHint=true and idempotentHint=true, and the description adds behavioral context about graceful degradation ('Partial failures degrade gracefully'), potential latency ('bundlephobia's first measurement on a new version can take 5-30s'), and how failures are reported ('sources_failed will list it if it times out'). This exceeds the safety profile given by 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-loading the core purpose in the first sentence, then providing usage, output, and failure info without redundancy. Each sentence adds new, actionable information for the agent.

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

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

Given the tool's composite nature and lack of an output schema, the description fully accounts for return values (summary block fields, per-advisory detail, links, alternative versions), ecosystem limitations, and failure modes. No critical context appears missing.

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

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

Schema already documents both parameters with 100% coverage, including scoped package support and default version behavior. The description does not add additional parameter-level detail beyond restating 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 identifies it as a composite check for deciding whether to add an npm package, listing both data sources (deps.dev, bundlephobia) and output fields. This distinguishes it from sibling research tools by its specific npm/package scope and composite nature.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides when-not-to-use and alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear 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?

The description discloses rich behavioral details beyond the annotations: returns top-N passages with character offsets and similarity scores, enables quote verification, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and enforces a 200K-char cap with truncation flagged. This far exceeds the minimal readOnly/idempotent hints.

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

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

The description is four sentences, each dense with purpose: the first defines the core action, the second specifies use cases and output, the third names a sibling integration, and the fourth gives technical constraints. The most important information is front-loaded, 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?

Despite not having an output schema, the description fully explains what the agent can expect (passages, offsets, similarity scores). It also covers input size limits, truncation behavior, and the embedding approach. For a tool with only three parameters, this is complete and self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3; however, the description adds meaning by explaining that 'text' is 'the text you already pulled' and gives concrete query examples ('supply-chain risk', 'drug interactions with warfarin'), helping the agent craft effective queries. It also clarifies that text is the source to search within, not a general input.

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

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

The description opens with 'Semantic search INSIDE a fetched record' — a specific verb and resource — and clearly distinguishes this from sibling tools by emphasizing that it operates on already-fetched text rather than the wider corpus. It also names a complementary tool (ask_pipeworx_grounded), reinforcing 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?

Explicit guidance is provided: 'Use when the record is too big to cram into the prompt' and it explains how this tool saves context. It also pairs with ask_pipeworx_grounded, giving a concrete alternative workflow and making the when-to-use vs. alternatives clear.

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

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

Beyond annotations, it discloses auth requirements, phone verification steps, SMS rate cap (10/day), webhook HMAC signing, and auto-disable after 10 consecutive failures. This significantly enriches the agent's understanding of side effects and constraints.

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 logically structured: purpose → return → auth → types → delivery. Each clause adds essential information; length is justified by the tool's complexity.

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

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

For a complex subscription creation tool with no output schema, the description covers prerequisites, all type variations, delivery channels, limits, and return value. Sibling tools handle listing/unsubscribing, so no missing 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?

While the schema already documents all parameters, the description adds practical examples (e.g., items:['5.02'] = officer change) and clarifies delivery-channel requirements (verified phone for SMS, webhook secret returned once). This goes beyond bare schema descriptions.

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

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

The description opens with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream,' and specifies the return value (new subscription id). It clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 states prerequisites (Pipeworx OAuth account), enumerates supported subscription types, and contrasts the always-on feed (pullable via recent_alerts) with optional email/SMS delivery, implying when subscription is needed vs. one-off pulls. It does not explicitly name alternative tools, but the context is sufficient.

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

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

Annotations already declare read-only/idempotent; description adds the return structure (category-bucketed examples with tool+argument shape) and the no-argument vs topic-focused behavior. This provides useful behavioral context beyond the annotations.

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

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

The description is detailed but well-structured: it starts with query phrasings, defines the tool's purpose, lists categories, and explains usage. Each sentence serves a 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?

The tool has no output schema and 1 optional parameter. The description covers when to use, how to call (with/without topic), what it returns, and how it relates to meta-tools. This is sufficient for an agent to invoke correctly.

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

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

Schema description already covers the topic parameter values. The description adds examples ('finance', 'pharma', 'betting') and clarifies the effect of passing a topic (focus the spread), adding value.

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

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

The description clearly identifies the tool as the onboarding entry point, stating it returns category-bucketed example questions with exact tool + argument shape. It distinguishes from siblings by advising 'Use this FIRST' when the agent doesn't know what Pipeworx can do.

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

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

Explicitly gives the when: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also indicates the optional topic parameter for focus. However, it doesn't mention explicit alternatives like discover_tools or when not to use it.

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

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

The description adds significant behavioral detail beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events accessible via recent_alerts. This aligns with destructiveHint=false and enriches the agent's understanding of 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 concise, front-loaded with the core action, and uses two sentences to convey all necessary information without any filler. Every word earns its place.

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

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

For a simple one-parameter tool, the description covers the core action, side effects, and data consequences. It doesn't describe the return value or error cases, but given the simplicity and the absence of an output schema, this is not a significant gap.

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

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

The input schema already fully describes the only parameter ('id' as a uuid returned by subscribe) with 100% coverage. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription). It distinguishes from siblings like subscribe and list_subscriptions by specifying the exact operation and ownership enforcement.

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

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

The description clearly implies when to use this tool (to cancel a subscription) and provides an important boundary (ownership enforced, only your own subscriptions). It doesn't explicitly describe alternatives or exclusions, but the context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description discloses internal behavior: two-pipeline architecture, verbatim evidence, judgment step, verdict vocabulary, and the precise meaning of could_not_verify (verification_error) versus unsupported. This is rich behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with trigger phrases and usage, then flows into pipeline specifics, return values, and critical caveats. Every sentence adds operational value; it is detailed but not redundant, appropriately sized for a complex tool that replaces multiple steps.

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

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

Given no output schema, the description thoroughly covers return values (verdicts, actual value, citation, reasoning) and error semantics (could_not_verify vs. unsupported). It also covers both pipeline paths and the tolerance parameter, making it complete for an AI agent to invoke correctly in a wide range of claim-checking scenarios.

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 schema coverage is 100%, the description adds meaningful semantics: it explains how tolerance_pct interacts with the 'percent-delta math' and recommends 1–2 for hallucination detection, which goes beyond the schema's dry definition. It also clarifies the expected natural-language format for claim with examples.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific verb-resource pairing ('validate claim'). It distinguishes itself from sibling tools by stating it replaces 4–6 sequential calls and by detailing two distinct verification pipelines (structured SEC EDGAR vs. grounded), making its scope unambiguous.

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

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

It gives direct usage guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the routing logic for financial vs. other claims. It also provides important exclusion semantics for could_not_verify, telling callers not to treat it as evidence, which is practical when-to-use advice.

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