Septa

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. Description adds beyond annotations: explains default model cost implications (free), BYO key for Anthropic (direct billing), and return structure including per-model {score, confidence, signals, raw_response} and combined view. 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?

Four sentences, no redundancy. Front-loaded with main purpose and scoring. Efficiently covers default, optional key, return format, and use cases.

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

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

Given no output schema, the description adequately covers return structure (per-model and combined). Explains default, optional key, and scoring. Could mention that raw_response includes full model output, but overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, all parameters documented. Description adds value by explaining default model behavior and the effect of _apiKey (triggers Anthropic probing, BYO key). Also mentions output structure supplying context for parameters. Exceeds baseline 3.

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

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

Description clearly states it probes LLMs for brand/business visibility and scores it 0-100. Specific verb 'probe' and resource 'LLMs' with explicit use cases. Distinguishes from siblings by focusing on multi-model visibility scoring with default and optional Anthropic.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides context on when to use, but does not explicitly tell when not to use or name alternative sibling tools. Clear about default model and optional Anthropic key.

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 supplements the annotations (readOnlyHint, openWorldHint, etc.) by detailing that the tool routes to over 5,000 tools among 1,317 sources, fills arguments, and returns stable citation URIs. It also mentions it works on every tier and is a fast single call.

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 somewhat lengthy but every sentence adds value, covering purpose, usage, examples, and differentiation. Some repetition exists (e.g., listing example types), but overall it is well-structured and front-loaded with key guidance.

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 (many sources, multiple aliases, sibling tools), the description is remarkably complete. It covers when to use, examples, behavior, and limitations. The presence of annotations reduces burden, but the description still enriches understanding.

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% description coverage across six parameters (question and five aliases). The description does not add additional semantic meaning 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 clearly states that the tool routes user questions to a vast array of authoritative sources and returns structured answers with citation URIs. It distinguishes itself from related tools like ask_pipeworx_grounded and deep_research by specifying when each should be used.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use this tool versus alternatives. It lists many example questions and specifies when to step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part queries.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it is a 'full working router' with 'candidate routing improvements' and 'falls back to nothing,' meaning it is not a stub. This provides context about experimental behavior beyond what annotations convey. 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 fairly concise for the amount of information conveyed. It front-loads the key point ('Beta version of ask_pipeworx') and includes necessary details about experimental features and usage. However, it could be slightly trimmed without losing meaning, e.g., by removing some redundant phrases.

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

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

Given the complexity (router to 5,002 tools), the description explains the experimental feature, how it differs from stable, and that it is a fully working router. Annotations cover safety. There is no output schema, but the description notes identical response shape to ask_pipeworx. It is sufficiently complete for an agent to understand the tool's role and behavior.

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

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

Schema coverage is 100% with each parameter described as an alias for 'question'. The description does not add new parameter-level information, but it mentions that arguments are identical to ask_pipeworx, which provides some context. Since the schema already fully describes parameters, a baseline score of 3 is appropriate.

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

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

The description explicitly states it is a beta version of ask_pipeworx, a universal router with 5,002 tools, using the same arguments and response shape. It clearly distinguishes from sibling tools by mentioning it has candidate routing improvements (source-preference ranking). The verb 'ask' and resource 'Pipeworx Beta' are specific, and the experimental nature is highlighted.

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

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

The description says 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This gives clear context on when to use it (for testing new routing) and implies it is not for stable use. However, it does not explicitly state when not to use alternatives, such as for critical or production queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: costs an extra LLM call, returns explicit refusal reasons, and explains the extraction process. 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 fairly long but well-structured and front-loaded with the key purpose. Each sentence adds value, though some minor redundancy exists. It efficiently conveys all necessary information.

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

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

Given the tool's complexity (routing across many tools and sources) and lack of output schema, the description fully explains the return format, refusal reasons, and use cases. It is complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% for 6 parameters, but all are aliases for one question parameter. The description's parameter explanation ('Your question in natural language. Accepts query, q, prompt, text, input as aliases.') largely repeats schema descriptions, adding minimal new value. Adequate for a single-parameter tool.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing, fetching, and extracting answers. It distinguishes itself from sibling tool 'ask_pipeworx' by noting the extra cost and use cases.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and lists examples. Also advises to 'prefer ask_pipeworx for casual lookups', providing clear guidance on 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 extensively discloses behavioral traits beyond annotations: fan-out logic, resolver contract (market_match_confidence, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread handling, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long (multiple paragraphs) but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Each part adds value, but it could be more concise; the level of detail may overwhelm some agents.

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 and lack of output schema, the description fully explains return shapes, evidence packets, resolver fields, safety mechanisms, and edge cases. It is highly complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: input formats (slug, URL, question text), depth options (quick vs thorough with explanation), and include_raw (when to use). Examples in schema and description enhance understanding.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet via Pipeworx), and provides usage examples ('should I bet on X'). This distinguishes it from sibling tools like ask_pipeworx or polymarket_arbitrage.

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

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

The description includes explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives examples of inputs (slug, URL, question text). While it doesn't explicitly state when not to use or name alternatives, the context and examples provide clear guidance.

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

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

Annotations already declare readOnlyHint=true, but description adds useful context: handles off-calendar fiscal years correctly, sorts by primary metric, returns citation URIs. No contradiction.

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

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

Description is slightly long but well-structured with example queries at the start. Every sentence adds value. Front-loaded with common use cases.

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 only 2 params and no output schema, description fully covers behavior, data sources, sorting, and output format. No gaps.

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

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

Schema coverage is 100%, but description adds rich meaning: explains enum values (company/drug) with data sources and examples for values array (tickers/CIKs for company, drug names). Goes beyond 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?

Clearly states it compares 2-5 companies or drugs side-by-side, with specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs). Distinguishes from sibling tools like entity_profile by explicitly saying it replaces sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and explains when to use each type (company vs drug).

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 details behavioral traits beyond annotations: expected latency (15-60s, up to ~90s for thorough), parallel decomposition, return fields (findings, gaps, contradictions, hop, citation_uri), and semantic excerpting. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 thorough but verbose, packing many details into several sentences. It is well-structured with front-loaded essentials (account, alternatives) followed by behavioral details. A slight trim would improve conciseness, but 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?

Given the tool's complexity (no output schema, rich annotations), the description covers all necessary context: input requirements, usage scenarios, behavior, limitations, and expected output. Nothing is left unexplained.

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 rich context: depth parameter explains facet counts and hop behavior per level; question parameter clarifies natural language and multi-part suitability. This goes well beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose: grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and returning a findings packet with evidence, confidence, and citations. It distinguishes from siblings like ask_pipeworx and open-web search, making the purpose very clear.

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

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

The description provides explicit guidance on when to use deep_research (broad/multi-part questions over structured data) versus alternatives: ask_pipeworx for single lookups or breaking news. It also notes account requirements and depth plan tiers, complete with fallback instructions. This is comprehensive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: 'each result is ready to call directly, no second schema lookup needed.' 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 a single coherent paragraph without wasted words. Every sentence adds value: purpose, usage, examples, output details, and a call to action. Could be slightly more structured (e.g., bullet points) but is already efficient.

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 (6 params, no output schema), the description sufficiently explains the output: 'top-N most relevant tools with names, descriptions, and full input schemas.' It covers result format and usage context, though more detail on sorting/relevance could enhance 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 coverage is 100% with descriptions for all 6 parameters. The description adds meaning by explaining that 'query' accepts natural language and listing aliases (task, q, search, description). This goes beyond the schema, earning 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 specifically states the tool's purpose: 'Find tools by describing the data or task' and details that it returns the top-N most relevant tools with names, descriptions, and full input schemas. It clearly distinguishes from sibling tools which are domain-specific, making this a meta-tool for discovery.

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 advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides example tasks and domains (SEC filings, FDA drugs, etc.), giving clear context for appropriate use.

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

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

The description discloses fan-out behavior across multiple sources, soft-failure for patents, output structure (up to 5 filings, fundamentals sorted, etc.), and input format requirements. Annotations already indicate readOnly and idempotent, but the description adds valuable context beyond these.

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

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

The description is front-loaded with example queries and compactly lists all return components. While slightly verbose, every sentence adds critical information, making it efficient for an AI 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 no output schema, the description comprehensively explains all return fields (CIK, filings, fundamentals, patents, news, LEI), including formatting and fallback behavior. It also covers constraints like soft-fail and name limitation.

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 description adds modest value by providing examples (ticker 'AAPL' or CIK '0000320193') and clarifying that names are not supported. It reinforces the enum restriction on 'type'.

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 specific verbs ('profile', 'fans out') and clearly identifies the resource ('US public company'). It distinguishes itself from siblings by explicitly stating it should be preferred over chaining individual lookups and noting that 'resolve_entity' should be used for names.

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

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

The description explicitly states when to use this tool (holistic view of a US public company) and when not to (if only a name is provided, use resolve_entity first). It also provides clear examples of appropriate queries.

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

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

Annotations already provide destructiveHint and idempotentHint, and the description adds no new behavioral details beyond stating deletion. 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?

Two concise sentences: first defines action, second provides usage guidelines. No redundancy or extraneous information.

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

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

Given the simple single-parameter tool with full schema coverage and informative annotations, the description is complete. It covers purpose, usage, and pairwise hints without needing to explain return values.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description does not add any additional meaning beyond the schema.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key', distinguishing it from related sibling tools like remember and recall. The purpose is 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?

Explicitly describes when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall, providing clear usage context.

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

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

Annotations already indicate read-only, idempotent, and not destructive. The description adds value by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown. It does not contradict annotations and provides behavioral context beyond them.

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

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

The description is two sentences, front-loaded with the primary action, followed by a bulleted list of use cases. Every sentence earns its place with no redundant 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?

Given two well-described parameters, no output schema, and informative annotations, the description is mostly complete. It explains the output (text blob) and use cases. It could mention error handling or limitations, but the current level suffices.

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

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

Schema coverage is 100% with both parameters described. The description does not add new semantic meaning beyond the schema; it only restates the tool's purpose. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a llms.txt file for any URL for AI crawlers. It specifies the actions (fetch, extract, emit) and the output format. This distinguishes it from siblings like ai_visibility_check and scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI crawler view. It does not explicitly exclude alternatives or state when not to use, but the context is clear enough for selection.

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

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

Annotations already declare read only and idempotent. Description adds value by specifying default behavior (active only) and listing returned fields, enhancing transparency beyond annotations.

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

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

Two efficient sentences: first states what it does and returns, second gives use cases. No redundancy, perfectly front-loaded.

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

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

Despite no output schema, description enumerates return fields. Parameter behavior and default are covered. Annotations handle safety. Complete for a simple list tool.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3. Description does not add further semantics beyond the schema's description of include_inactive, but it connects the parameter to the 'active' default.

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 (List), resource (the caller's active subscriptions), and specifies the return fields. It distinguishes itself from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Context implies when not to use (management actions go to subscribe/unsubscribe). Clear and helpful.

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

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

Discloses rate limit (5 per identifier per day), free usage, and that feedback is read daily and influences roadmap. Annotations do not contradict; description adds relevant behavioral context beyond the structured fields.

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?

Concise and well-structured: begins with purpose, then usage scenarios, important dos and don'ts, and constraints. Every sentence provides valuable information without redundancy.

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

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

For a feedback tool with no output schema, the description covers all necessary context: what to communicate, how to format, constraints, and expected impact. Complete and self-contained.

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?

All parameters are fully described in the schema (100% coverage). The description adds extra guidance: for message, it recommends specificity and length limits; for type, it clarifies enum meanings; for context, it notes it's optional. Adds significant value beyond 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 allows users to send feedback about bugs, features, data gaps, or praise, with specific examples. It distinguishes itself from sibling tools which are all inquiry or data retrieval tools, not feedback submission.

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 (bug, missing feature, praise) and includes important notes: describe in terms of Pipeworx tools/packs, don't paste end-user prompt, rate-limited to 5/day, free and doesn't count against quota. Provides complete usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that it's self-aggregating from CF analytics-engine, no PII, and cached 5min-1h depending on window.

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?

Concise, well-structured, front-loaded with output, then use cases, then technical details. Every sentence adds value with no 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?

No output schema, but description mentions return structure (top tools, top packs, total call volume) and caching behavior. Sufficient for a read-only trending tool.

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

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

Schema covers 100% of the single parameter. Description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' providing meaning beyond the enum values.

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

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

Clearly states 'Returns the top tools, top packs, and total call volume over a recent window.' Verb+resource is specific and distinct from siblings like ask_pipeworx or discover_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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment). Provides caching duration. Does not explicitly state when not to use, but use cases are clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false. The description goes far beyond these: it explains semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slugs >20% null), fill check logic (theoretical vs realizable edge at book depth), and response structure. No contradiction with annotations.

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

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

The description is comprehensive but somewhat lengthy; however, every sentence adds value. It is front-loaded with the main purpose. Minor improvement could be using bullet points for the modes, but as prose it is clear and well-structured. 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 no output schema, the description thoroughly explains the response format: opportunities[] with fields like gap_pp, suggested_trade, reasoning, and partition_check details. It covers edge cases (skipped_low_similarity, placeholders_filtered, fill_check conditions). The tool is complex, and the description makes it fully usable.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description adds significant context: for event, it explains it walks child markets and checks date-axis/threshold-axis ordering and partition_check; for topic, it searches related events and flattens markets. This contextualizes parameters well 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for single-event, and topic for cross-event scanning. The verb 'find' and resource 'arbitrage opportunities on Polymarket' are specific and differentiate from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It provides detailed guidance, including when not to trade based on fill_check results, and mentions alternative tool polymarket_fill_risk for custom sizing. No ambiguity.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral details: caching at KV level (1h), three model families, Fed bet exclusion, and response structure. 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 and dense with technical details, which may overwhelm an AI agent. However, it is well-structured with logical sections (purpose, model families, response segments, knobs, caching). Could be more concise, but the structure aids readability.

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 thoroughly explains the response structure (by_segment, diagnostics, etc.), caching behavior, filter knobs, and model logic. This makes the tool's behavior and outputs highly predictable for an agent.

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

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

The input schema has 100% coverage with detailed descriptions. The tool description adds value by explaining the role of knobs (e.g., tradeable-edge filters) and the distinction between min_kelly and min_partition_leg_kelly, enhancing parameter understanding beyond what the schema 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 purpose: 'scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge opportunities from model-driven analysis.

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

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

The description explicitly targets 'what should I bet on today' use case and mentions discoverability without paging. It lists filter knobs (e.g., min_liquidity, max_spread_pp) for tailoring usage but does not explicitly contrast with sibling tools or state when to avoid using this tool. Still, the context signals and sibling names provide implicit guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: it reads from daily snapshots, has a 60-day snapshot TTL, decay numbers are from daily closes (not intraday), and gaps in snapshots mean no scan that day. 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 somewhat lengthy but front-loaded with the core purpose. It explains the output structure in detail (tracked, expired, snapshot_dates). While every sentence adds value, it could be slightly more concise without losing critical details.

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

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

Given the tool has 2 parameters (none required), no output schema, and high schema coverage, the description is remarkably complete. It explains the output fields, limitations (60-day TTL, no intraday), and practical implications (snapshot gaps, median lifespan). No gaps identified.

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

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

Schema coverage is 100% with both parameters described, but the description adds practical context beyond the schema: default/limit for days, snapshot family for window, and explains history depth bounded by TTL. This provides additional semantic value.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage (different domain).

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

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

The description explains when to use the tool: to assess edge persistence vs. fresh edges ("a fresh wide edge and a 3-week-old wide edge are different trades"). It does not explicitly state when not to use it or list alternatives, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, which the description does not contradict. It adds rich behavioral details: walks the ladder, return fields like top_of_book, vwap_fill_price, slippage_pp, verdict, and explains forced directional risk in basket mode.

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 purpose, uses clear headings for modes, and every sentence adds value. Slightly verbose but well-structured 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, the description thoroughly explains return fields for both modes, covers potential pitfalls, and provides complete guidance for safe usage.

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% but the description adds significant context: how size_usd is interpreted differently per mode, default side behavior in basket mode, and clarification of market vs event parameters.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_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?

Explicitly advises using this tool before acting on 'any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the risk of partial fills leading to unhedged positions.

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

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

Annotations already declare read-only, idempotent, and open-world. The description adds significant behavioral context: compatibility_warning (two cases), temporal_alignment, skipped_cross counters, and explains when spreads are meaningless. 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 well-structured with clear sections for purpose, modes, response, and safety fields. It is lengthy but every sentence adds essential information, making it effective for an agent.

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

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

Despite lacking an output schema, the description details the response format (leg-by-leg prices, spread array, safety fields) and covers edge cases like non-equivalent bet shapes and temporal misalignment. This is complete for an agent to understand tool behavior.

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

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

Schema has 100% coverage with parameter descriptions. Description adds value by explaining how topic vs explicit parameters interact, providing examples and the override behavior. This goes beyond the schema's enum list and 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 it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by being cross-venue.

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

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

The description explains two usage modes with pre-mapped vs explicit parameters and includes warnings about compatibility and rarity of tradeable spreads. It implicitly tells when to use (when comparing same event across venues) but could more explicitly contrast with intra-venue arbitrage 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 read-only, idempotent, non-destructive. Description adds scoping detail (by identifier) and clarifies that omitting key lists all keys. No contradiction.

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

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

Three sentences efficiently cover purpose, usage, and pairing. No filler; front-loaded with key action.

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

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

Complete for a simple retrieval tool: covers retrieval, listing, scope, and sibling relationships. No missing critical info.

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% (single param 'key' described). Description adds value by explaining behavior when omitted (list all keys), which is beyond the schema.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. Distinguishes from sibling tools remember and forget by specifying the complementary actions.

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?

Explains when to use (look up stored context) and alternatives (pair with remember/forget). Does not explicitly state when not to use, but 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 readOnly, idempotent, and non-destructive behavior. The description adds context about mark_read statefulness ('so the next call only shows newer ones') and confirms polling safety. 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?

Two sentences packed with information: main action, return structure, parameters, and alternative access. No wasted words; front-loaded with core purpose.

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

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

Despite no output schema, the description details return fields (source, citation_uri, payload). Covers all parameters implicitly and mentions polling suitability. Provides complete context for a read-only feed tool.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds value by explaining the effect of mark_read ('flag returned events read in the same call') and the purpose of limit, which are not fully captured in schema alone.

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

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

The description clearly states 'Pull fired events from your subscription feed' and details what is returned (source, citation_uri, raw payload), with filtering options. It distinguishes itself from siblings by specifying its unique functionality for recent alerts.

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

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

Explicitly states that polling works fine and provides an alternative GET endpoint for scripts/dashboards, guiding when to use this tool vs. other access methods. Also explains mark_read behavior for sequential calls.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds detailed behavioral traits: sources used (SEC EDGAR, GDELT→GNews, USPTO), failure modes (PatentsView sunset, rate limits), and return structure (grouped changes, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is moderately long but well-structured, front-loading example queries and then detailing sources and fallback. Every sentence adds value, though it could be slightly more concise.

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

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

Given 3 required parameters, full schema coverage, no output schema, the description is complete: it explains return format, mentions alternatives (entity_profile), and covers edge cases (rate limits, sunset). No gaps remain.

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 schema already documents all parameters. The description adds minor value by providing usage examples for `since` (e.g., '30d', '3m') and clarifying input formats for `value`, but no additional semantic depth beyond 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 provides a change feed for a company covering SEC filings, news, and patents. It distinguishes from the sibling tool entity_profile by contrast, and uses specific verb phrases like 'What's new with X'.

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 provides example queries ('What's new with X', 'latest on Y') and tells when to use entity_profile instead. Also explains fallback behavior between GDELT and GNews, giving clear context for use.

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

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

Annotations already indicate idempotent and non-destructive. Description adds scope (key-value, scoped by identifier) and retention policies (persistent vs 24h). No contradictions; complements annotations well.

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

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

Every sentence adds value: purpose, when to use, storage details, retention, paired tools. It is front-loaded with the primary action and examples. 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?

For a simple 2-parameter tool with 100% schema coverage and no output schema, the description fully covers usage, retention, and integration with sibling tools. No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. The description provides real-world usage patterns like 'subject_property', 'target_ticker', adding meaning beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with concrete examples like 'a resolved ticker, a target address'. It distinguishes from siblings 'recall' and 'forget' by mentioning pairing with them.

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

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

Explicitly states when to use: when discovering something worth carrying forward. It also differentiates behavior for authenticated users (persistent) vs anonymous sessions (24 hours), providing clear context for decision-making.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description further discloses that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups, and provides return format details for each type. 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 moderately sized and well-structured, starting with example queries and a clear purpose statement. It efficiently packs details about types and outputs without excessive verbosity. Minor room for trimming, but overall concise.

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

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

Given no output schema, the description adequately explains return values for both entity types and notes the cascading nature. It covers the main usage context but could mention error handling or edge cases (e.g., ambiguous names). Still sufficient for most use cases.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing examples (e.g., ticker, CIK, name for company; brand/generic for drug) and clarifying auto-disambiguation. This goes beyond the schema's basic 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 resolves user-spoken names to canonical identifiers, provides example queries, and distinguishes itself from siblings by focusing on ID lookup. It specifies supported entity types (company, drug) and their outputs, making the purpose unambiguous.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing a clear directive. It does not explicitly list when not to use or alternatives, but the context from siblings (e.g., entity_profile) implies differentiation. Slightly lacking in exclusion criteria, but strong 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by detailing the probing process, ranking, and output fields (score, confidence, signal density per entity). 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?

Three concise sentences front-loaded with the main action. Every sentence adds value: comparison, method, use case, and output. No 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?

Given no output schema, description explains return format (ranked list with score/confidence/signal density). Covers process and use case. Could mention entity count limit (2-8, from schema) but not essential. Overall adequate.

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

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

Schema coverage is 100%, baseline 3. Description adds context beyond schema: first entity treated as subject, models default to workers-ai, context disambiguates. This provides useful usage nuance without repeating 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 compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single probe) and compare_entities (generic comparison) by specifying the competitive AI-marketing audit use case.

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

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

Provides clear context for when to use: competitive AI-marketing audits, with an example question. Implicitly, for single entity use ai_visibility_check instead, but does not explicitly state when not to use or list alternatives beyond the implied sibling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: partial failures degrade gracefully, first bundlephobia measurement can take 5-30s, and sources_failed will list timeouts. 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 relatively long but well-structured: opens with purpose, then usage, return summary, ecosystem scope, and failure behavior. Every sentence is informative; minor redundancy ('fans out across...') could be tightened, but overall efficient.

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 lists return fields in detail (summary block, per-advisory, links, alternative versions). It covers inputs, outputs, constraints (NPM only in v1), and edge cases (partial failures, timeout behavior). Complete for a complex multi-source tool.

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

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

Schema coverage is 100% with both parameters described. The description reinforces that scoped packages are accepted and version defaults to latest, but adds no new syntax or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs a composite check for adding an npm package, covering license, advisories, bundle size, and more. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings (none of which do similar package analysis).

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost. Also specifies what NOT to use for (PyPI, Maven, etc.) and provides a fallback alternative ('deps.dev:version directly'), giving clear context for tool selection.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the embedding model (BGE-base-en), window size (500 chars), character cap (200K), and truncation with flagging—essential behavioral details.

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

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

Three sentences efficiently cover purpose, usage, technical details, and limits. Front-loaded with primary action, then context, then implementation specifics—no 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?

Without output schema, description details return values (passages, offsets, scores) and constraints. Combined with rich annotations and complete parameter info, the definition fully equips an agent.

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

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

Schema coverage is 100% but the description adds value: explains 'text' max size, provides 'query' examples, and specifies 'limit' range and default—enhancing schema meaning.

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

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

The description clearly states the verb 'semantic search' and the resource 'inside a fetched record', distinguishing it from siblings like ask_pipeworx_grounded. It specifies the output (passages with offsets and scores) and the use case (large records).

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 advises when to use ('too big to cram into the prompt') and recommends pairing with ask_pipeworx_grounded, providing clear context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about the nature of alerts and optional route filtering, but does not disclose significant additional behavioral traits 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 concise at two sentences plus an example, with no wasted words. It is front-loaded with the core purpose and uses the example to illustrate usage. Slightly more structure (e.g., breaking into bullet lists) could improve scanability, but it is still efficient.

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 (one optional parameter, no output schema), the description covers the input behavior completely. It explains both the single-route and system-wide use cases. The lack of output schema explanation is acceptable since it is not present.

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

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

Schema coverage is 100% and the schema description already covers the route parameter well. The description adds value by providing concrete examples, alternative naming conventions, and the exact behavior for omitting the parameter, which aids the agent in constructing valid invocations.

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 provides SEPTA service alerts, advisories, detours, and suspensions for Philadelphia transit. It specifies the resource (alerts for various transit modes) and distinguishes itself from siblings like septa_bus_positions by focusing on alerts rather than real-time positions or arrivals.

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: pass a route to check one line, omit for all active alerts. It provides examples and lists acceptable formats. It does not explicitly state when not to use tool (e.g., for positions), but this is implicit from the sibling tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying auto-translation of legacy trolley numbers and listing returned data fields (crowding, lat/lon), which are not in annotations. No contradictions found.

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?

Exceptionally concise—single sentence plus an example and technical details. Every element serves a purpose: purpose, field list, input format, example. No redundant 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 one-parameter read tool with strong annotations, the description covers input quirks and output data adequately. Minor gap: no mention of result limits or pagination, but not critical for this 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?

Schema has 100% description coverage for the single parameter, but the description adds notable extra context: auto-translation behavior for legacy trolley numbers and an explicit example. Enhances understanding 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 identifies the tool as retrieving live SEPTA bus and trolley positions per route, listing specific fields (direction, destination, next stop, crowding, lat/lon). It distinguishes itself from siblings like septa_alerts and septa_next_to_arrive by focusing on real-time vehicle positions.

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

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

Provides a concrete example (septa_bus_positions({ route: "23" })) and explains route input formats (bus numbers vs trolley codes, with auto-translation). Lacks explicit when-not-to-use instructions but offers enough context to infer appropriate use.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds concrete details: returns direct and connecting itineraries with transfer station, departure/arrival times, live delay status, and fuzzy matching for station names. 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 compact and front-loaded with the core purpose. The example is helpful but adds length. Very few redundant words; every sentence contributes unique value.

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

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

No output schema exists, so the description must explain return values. It covers direct and connecting itineraries, transfer stations, times, and delay status. The example demonstrates expected usage. For a tool with 3 parameters and moderate complexity, the description is adequate.

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

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

Schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds value by providing a full example call with real station names and clarifying that stations are fuzzy-matched, which is not in schema. It also implicitly reinforces the meaning of 'n' as number of upcoming trains (default 3, max 10).

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

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

The description explicitly states the tool returns 'Next SEPTA Regional Rail trains from an origin station to a destination station in Philly — direct trains and connecting itineraries, departure/arrival times, and live delay status.' It includes an example and clearly distinguishes from siblings like septa_rail_arrivals (which likely shows all arrivals) by focusing on route-based queries.

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

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

The description implies usage for answering 'when is the next train from X to Y' but does not explicitly state when to use this tool versus siblings (e.g., septa_rail_arrivals for station arrivals) or provide conditions for not using it. The example provides context but no alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context, such as fuzzy station name matching and the output structure (grouped northbound/southbound, live status). 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?

Two concise sentences, front-loaded with the core purpose, minimal redundancy, and every sentence adds value.

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

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

Despite no output schema, the description enumerates returned fields (train number, line, destination, times, status, track), and covers the critical fuzzy matching behavior. Sufficient for an agent to use the tool effectively.

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

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

Schema has 100% parameter coverage. The description adds examples and details about fuzzy matching, default results (8), and max (30), enhancing the schema's meaning.

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

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

The description clearly states it provides a 'departures board' for a station, listing specific fields. However, it does not differentiate from sibling tools like septa_next_to_arrive, leaving room for ambiguity.

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

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

The description implies usage for specific stations with fuzzy matching, but does not explicitly state when to use this tool over alternatives (e.g., septa_next_to_arrive) or provide exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by listing the specific output fields (train number, line, destination, current/next stop, minutes late, lat/lon), which is useful context beyond annotations.

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

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

Two sentences and an inline example. Every sentence contributes: purpose, use case, filter example. Compact and well-structured.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, parameter, and output fields. Annotations further ensure safety transparency.

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

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

Schema coverage is 100% and the parameter description lists valid line options. The description adds an example usage and restates the filter option, making it clearer than the schema alone.

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

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

The description uses a specific verb 'Live positions' and identifies the resource 'every SEPTA Regional Rail train'. It clearly distinguishes from sibling tools like septa_alerts or septa_bus_positions by focusing on train positions including lat/lon and late status.

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

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

The description states when to use it: to check train positions and lateness. It provides an optional filter example. However, it does not explicitly mention when not to use it or compare directly to siblings like septa_next_to_arrive.

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

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

Discloses that anonymous/BYO cannot persist subscriptions, delivery channel limits (10 SMS/day, webhook auto-disabled after 10 failures), and phone verification requirement. Annotations already indicate non-read-only and non-destructive; description adds context beyond annotations. Idempotency hint not explained.

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?

Well-structured with purpose first, then types, then delivery. Slightly verbose due to extensive examples but every sentence adds value. Could be tightened without losing clarity.

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

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

Covers all key aspects: creation behavior, required account, type variants, delivery channels, return value (subscription id), and webhook secret. No output schema but description adequately explains response.

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?

Description adds extensive meaning beyond schema: explains each type's params with concrete examples, delivery options with constraints, and webhook signing details. Schema coverage is 100% but description enriches understanding.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream. Distinguishes 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?

Provides explicit requirements (Pipeworx OAuth account), type-specific examples, and delivery constraints. Lacks explicit contrast with other subscription-related tools but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds that it returns category-bucketed examples with exact tool+argument shapes, providing context beyond annotations.

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

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

The description is comprehensive but slightly long; it includes aliases, purpose, return details, and usage instructions. It could be more concise but is well-organized.

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

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

Given a single optional parameter, no output schema, and the tool's simple nature, the description fully covers what it returns, how to use it, and what topics are available.

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

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

Schema coverage is 100% and the description explains the topic parameter, its optional values, and the default behavior, adding meaning beyond the schema.

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

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

The description explicitly states its purpose as an onboarding entry point, returns category-bucketed example questions, and distinguishes from sibling tools like ask_pipeworx or discover_tools by its role in introducing capabilities.

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

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

It clearly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also implies alternatives by listing related tools and topics.

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 non-destructive, idempotent behavior. The description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This goes beyond annotations to explain persistence of historical data.

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

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

Two sentences, both essential. The first states the core purpose, the second adds behavioral constraints. No wasted words, front-loaded structure.

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 (one parameter, no output schema), the description is fully complete. It covers purpose, ownership, behavioral effect, and relation to sibling tool recent_alerts.

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

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

Schema coverage is 100% for the single parameter 'id', which is well-documented in the schema as 'Subscription id (uuid) returned by subscribe.' The description adds no additional parameter semantics beyond what the schema 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 'Cancel a subscription by id.' with a specific verb (cancel) and resource (subscription). The title 'Unsubscribe from Alerts' and sibling 'subscribe' provide clear distinction.

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 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context for when to use. It does not explicitly mention alternatives, but the purpose is unambiguous.

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

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

The description adds significant behavioral context beyond the annotations, such as the two processing paths (structured vs. grounded), the return verdict options, the tolerance override mechanism, and the efficiency claim (replaces 4-6 sequential calls). Annotations already declare readOnlyHint=true and idempotentHint=true, which are consistent. 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 somewhat lengthy but well-structured, starting with trigger phrases, then use case, then detailed behavior. Every sentence adds value, and the length is justified by the complexity of the tool (two paths, return types, tolerance override). 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?

Despite the absence of an output schema, the description thoroughly explains the return format (verdict, value, citation, reasoning) and the internal logic (two pipelines). It also covers usage context and parameter semantics well. For a complex tool, this is highly complete.

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

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

Schema description coverage is 100% with both parameters documented. The description adds value by providing examples for the 'claim' parameter and explaining the purpose and override behavior of 'tolerance_pct' (e.g., for hallucination detection). This goes beyond the basic 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 clearly identifies the tool as a claim verification tool with specific trigger phrases ('Is it true that...', 'fact check', etc.) and distinguishes it from sibling tools like ask_pipeworx by focusing on factual claims and providing two specialized pipelines (SEC EDGAR for financials, grounded pipeline for other claims).

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 ('whenever the agent needs to check whether something a user said is factually correct') and outlines the two sub-paths for different claim types. However, it does not explicitly state when not to use it (e.g., for opinion or non-factual queries), though the trigger phrases implicitly guide that.

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