Seo Backlinks

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description reveals the need for a user-provided API key for Anthropic, that Anthropic calls are paid directly to Anthropic, and details the return structure including per-model score/confidence/signals/raw_response.

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

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

The description is compact (4-5 sentences) with no redundancy. Every sentence provides essential information: probe function, default model, optional Anthropic, return fields, and use cases. Front-loaded with the main verb 'Probe...'.

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

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

Despite having no output schema, the description fully explains the return structure (per-model score, confidence, signals, raw_response, combined view). Parameters are fully covered in both schema and description. No gaps for an agent to use this tool correctly.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining the default model behavior and the purpose of `_apiKey` (bring your own key, direct payment to Anthropic), which is not fully detailed in the schema alone.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility per model, specifying the default model and optional Anthropic integration. It distinguishes from sibling tools like 'entity_profile' or 'deep_research' by focusing on AI visibility scoring.

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

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

Explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it lacks explicit 'when not to use' guidance, the context is clear enough for an agent to decide appropriately.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond these: it routes among 5,529 tools, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. It doesn't disclose failure modes or non-coverage, but with annotation coverage this is a solid transparency level.

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

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

The description is lengthy but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH', 'START HERE') and uses structured separators (Use whenever, Examples, Step up). Some redundancy exists ('START HERE' and 'default entry point' repeat the same idea) but overall it remains efficient for the breadth of behavior it must convey.

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 of a routing tool, the description covers when to use, what it returns (structured answer with citations), why it's preferred, and how it differs from alternatives. There is no output schema, but the description clearly states the return value includes citations, which is sufficient. It also accounts for tier limitations and gives examples, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%: all six parameters are aliases for the same natural-language question, and the schema already states they accept query/q/prompt/text/input. The description adds examples of real questions but doesn't clarify parameter syntax beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool routes questions to authoritative structured data sources with citations, listing concrete domains (SEC, FDA, FRED, etc.) and explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research by noting when to step up. The verb 'routes' plus the resource scope makes the purpose specific and distinct.

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

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

Usage guidance is explicit: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' with concrete 'when to use' phrases ('what is', 'look up', 'find') and named alternatives ('ask_pipeworx_grounded' for hallucination-resistant answers, 'deep_research' for multi-part questions). It also gives examples, making it easy for an agent to decide correctly.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it is a live experimental edge, currently identical to stable because the last candidate was retired, and it is a full working router that does not fall back to anything else. This goes beyond the annotations without contradicting them.

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

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

The description is longer than minimal but every sentence earns its place: it explains the beta nature, current state, usage directive, and confirms it is a full router. It is front-loaded with the key differentiator ('Beta version of ask_pipeworx') and structured logically.

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

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

Despite having no output schema, the description states 'same response shape' as ask_pipeworx, linking to the sibling's known behavior. It covers the tool's experimental nature, current parity with stable, and usage context. For a complex router, this is reasonably complete, though it assumes familiarity with ask_pipeworx.

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

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

Schema coverage is 100% with all alias parameters described, so the schema handles parameter semantics. The description only says 'same arguments' and 'use exactly like ask_pipeworx', adding no extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, stating it is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting experimental routing improvements, but it does not explicitly state the core function (e.g., answering questions by routing to internal tools), relying on the sibling's known purpose.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared with the stable router for merge decisions. It also clarifies the current state (no active candidate) so an agent knows it behaves identically right now. It does not mention when not to use it relative to ask_pipeworx_grounded, but the alternative ask_pipeworx is named.

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

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

The description goes well beyond annotations by detailing the return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}), possible refusal reasons, and the key behavioral constraint that the answer is extracted using ONLY what the tool result contains. It also discloses the extra LLM call cost, which annotations do not cover.

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

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

The description is appropriately sized for the complexity, with a clear structure: purpose, mechanism, return contract, usage criteria, and cost trade-off. Every sentence adds distinct value, and the key information is front-loaded.

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

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

Given that there is no output schema, the description fully documents the return format and refusal reasons. Combined with annotations, it covers all necessary context: when to use, how it routes, what it returns, when it refuses, and its cost relative to alternatives.

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

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

The input schema covers all six parameters (all aliases for question) with 100% description coverage, so the description need not repeat parameter details. The description adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction from tool results and explicitly naming the difference (extra LLM call).

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also notes the cost trade-off, making it easy for an agent to decide between this and the sibling tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: resolver contract with match confidence, parent event extraction, news fields with fallback, safety mechanisms for low-confidence matches and closed markets, and resolution-rule risk. 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 very long and dense, containing many important details but lacking brevity. It uses section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) but remains a wall of text. It could be more concise with bullet points or clearer separation of concerns.

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 of the tool (multiple classifiers, fan-out behavior, response shapes, safety checks), the description is comprehensive. It covers return values in detail (result.market, result.analysis, result.evidence), safety mechanisms, resolution-rule risk, and edge cases. No output schema exists, so the description fully bears the burden of explaining outputs.

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 three parameters. The description enriches these by explaining the depth parameter's effect ('quick = 2-3 evidence sources, thorough = full fan-out') and include_raw's purpose (summarized vs full payloads), adding value beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and distinguishes from siblings like ask_pipeworx and polymarket_arbitrage by focusing on comprehensive research for betting decisions.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains the depth parameter for quick vs thorough research. However, it does not explicitly state when not to use this tool or list alternatives, though the context of siblings implies its specialized role.

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

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

Annotations already provide readOnly, openWorld, and idempotent hints. The description adds significant behavioral context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 dense but well-structured, starting with trigger phrases and then detailing behavior. Every sentence adds value without redundancy. Highly efficient for the information conveyed.

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 moderate complexity (2 params, no output schema), the description thoroughly explains what data is returned per entity type, including sorting and citation URIs, making it complete for an AI 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%, so baseline is 3. The description adds value by explaining the mapping of entity types to data and giving example formats (tickers, names), going 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 clearly states 'side-by-side comparison of 2–5 companies or drugs in one parallel call' with specific triggers like 'Compare X and Y'. It distinguishes from sequential lookups, making its purpose unambiguous.

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

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

The description provides explicit triggers and a strong preference to use this tool over sequential lookups. However, it does not explicitly name alternative tools for single-entity lookups, leaving a minor gap in exclusion guidance.

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

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

The description goes far beyond the annotations by revealing behavior: it returns verbatim evidence, confidence, source, fetched_at, and a `pipeworx://` citation that is always fetchable; it never invents answers and reports explicit gaps[]; it performs gap recovery by depth; and it discloses timing expectations and semantic excerpting. No contradiction with annotations 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?

The description is long but every clause contributes critical operational detail (auth, alternatives, depth behavior, citation mechanics, timing). It is front-loaded with the account requirement and fallback tool. The only minor deduction is a dense, unbroken paragraph structure that could be more scannable, 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 high complexity and absence of an output schema, the description thoroughly covers what to expect: the findings packet, gaps[], contradictions[], citation_uri semantics, and latency. It also explains the multi-hop process and why results deep in long documents won't be missed. This fully equips an agent to invoke the tool and interpret results 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?

Although the schema fully describes both parameters, the description adds behavioral nuance: it explains the practical difference between quick/standard/thorough (facet counts, gap-recovery hops, contradictions scan), the paid plan requirement for 'thorough', and how the citation_uri is conditionally present. This significantly enriches the raw schema.

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

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

The description states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, and explains the decomposition into facets routed to 5,529 tools. It explicitly distinguishes itself from siblings like ask_pipeworx and open-web search, making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: it's for broad/multi-part questions over structured data, while single lookups and breaking news are assigned to ask_pipeworx. It even warns that deep_research returns mostly empty gaps for colloquial current-news topics. It also notes account requirements and suggests ask_pipeworx when not signed in.

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

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

Adds value beyond annotations by describing the return format (top-N tools with names, descriptions, schemas, examples) and that results are immediately callable. No contradictions with annotations (readOnlyHint=true, etc.). Could mention rate limits, but current detail is strong.

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

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

Description is 4 sentences, front-loaded with purpose and usage guidance. Lists many examples but they are relevant and informative. Could be slightly trimmed, but overall efficient and well-structured.

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

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

Despite lacking an output schema, the description fully explains what is returned (top-N tools with schemas, examples) and that results are ready to call. No missing details; the tool's behavior is completely described for an agent.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description provides example queries and mentions aliases, but does not add significant extra meaning beyond what the schema already provides. Baseline 3 due to high schema coverage.

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

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

The description clearly states 'Find tools by describing the data or task' and lists numerous specific domains (SEC filings, FDA drugs, etc.), making the tool's purpose immediately obvious and distinguishing it from siblings like search_within or validate_claim.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use guidance. Does not explicitly mention alternatives, but the context implies when discovery is needed.

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 and idempotentHint. Description adds useful behavioral context: patents API sunset May 2025 leads to soft-fail, requires zero-padded CIK, and mentions parallel fan-out. Some redundancy 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?

Well-structured with front-loaded examples and detailed bullet points. Every sentence earns its place, though slightly verbose for a description.

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 fully explains return data (CIK, filings, fundamentals, patents, news, LEI), soft-fail behavior, and required input format. Complete for a complex tool.

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

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

Input schema has 100% coverage with descriptions. Description adds clarifying context beyond schema, such as name resolution requirement and value format examples, enriching 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: 'full cross-source profile of a US public company in ONE parallel call.' It lists the sources and specific data returned, and distinguishes itself from siblings like resolve_entity.

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides an explicit alternative: 'use resolve_entity first if you only have a name.'

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 destructiveHint: true. The description adds behavioral context (stale context, sensitive data) but does not contradict annotations.

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

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

Three succinct sentences, no wasted words. Purpose and usage are front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and relationships with siblings.

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 'key'. The description mentions 'by key' but adds no further meaning beyond the schema description.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key'. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicit usage contexts are provided: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with siblings.

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

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

Annotations indicate the tool is read-only, idempotent, and non-destructive. The description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard markdown format. It also notes the output is a single text blob, which goes 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 concise with no wasted words. The main purpose is front-loaded, process details follow, and use cases are listed efficiently. 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?

Given no output schema, the description explains the output format (standard markdown, single text blob) and what it extracts. For a simple two-parameter tool, this is complete enough for an agent to understand the result.

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

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

Schema coverage is 100%, so baseline 3. The description does not add additional parameter details beyond the schema descriptions. The implicit use of 'url' and 'max_links' is covered by 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 generates a production-ready llms.txt file, specifying the verb 'Generate' and the resource 'llms.txt'. It distinguishes itself from siblings like ai_visibility_check by focusing on file generation rather than visibility checks.

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 lists three specific use cases (client indexing, drafting for own project, auditing competitor) which guide when to use the tool. It does not explicitly mention alternatives or when not to use, but the examples provide adequate 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 non-destructive behavior. The description adds value by detailing the return fields and the effect of the include_inactive parameter, which goes 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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence serves a clear function.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, and return values thoroughly.

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

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

Schema coverage is 100% with the include_inactive parameter already described. The description does not add meaningful extra information 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 it lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It is a specific verb+resource combination, distinct 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?

The description explicitly advises use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for when to use the tool, though it does not name alternatives.

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

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

Annotations are all false and provide no specifics, but the description discloses the claim_token workflow, rate limit (5/day), free/no-quota impact, daily team digest, and that feedback should reference Pipeworx tools/packs. This goes well beyond the structured fields, though it could mention side effects like creating a persistent record.

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

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

Single dense paragraph, front-loaded with purpose. Every sentence adds a distinct fact (scope, claim token, rate limit, quota). While a bit long, it remains efficient given the number of caveats and important behavioral nuances.

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, but the description explains the output (claim_token) and the subsequent recall workflow. It covers prerequisites (not for other servers), restrictions (rate limit), and practical usage, making it 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?

All 4 parameters have rich schema descriptions (100% coverage), so baseline is 3. The description adds value by framing the 'type' enum in terms of concrete scenarios (bug, feature, data_gap, praise) and clarifies how to use claim_token (pass it back later without other args). It also guides message content ('don't paste the end-user's prompt').

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

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

The description opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly differentiates from siblings like ask_pipeworx or deep_research by scoping to feedback about Pipeworx tools. The purpose is unambiguous and not a tautology.

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

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

Explicitly lists use cases (bug, feature/data_gap, praise) and explicitly excludes non-Pipeworx servers, directing users to file elsewhere. Also advises on what to include ('don't paste the end-user's prompt') and how to identify Pipeworx tools, giving the agent clear decision criteria.

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

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

Annotations already convey read-only, idempotent, non-destructive nature. The description adds valuable behavioral context: data is self-aggregating from CF analytics-engine, no PII, and cached for 5min-1h depending on window. 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 concise, front-loaded with purpose, and every sentence adds value. Use cases are bulleted logically. 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?

The tool is simple (1 optional param, no output schema). The description fully covers purpose, use cases, data source, caching, and privacy. No gaps given the 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 has 100% coverage for the single parameter 'window'. The description adds meaning by explaining shorter vs longer window trade-offs ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the enum labels.

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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs like 'returns' and 'calling on', and the resource (trending data) is well-defined. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending usage metrics.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical choice, and seeing alignment. It also notes window behavior (shorter for hot vs longer for steady-state). However, it does not explicitly state when to avoid using this tool or mention alternatives, so it's slightly incomplete.

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 as false. The description adds substantial behavioral detail: the algorithmic checks (monotonicity violations, partition-sum), the fill check against live CLOB depth, semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs), and output structure. No contradiction with annotations; it extends transparency 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 lengthy but well-structured: it opens with a clear purpose, then explains each mode, followed by algorithmic details, output format, and fill check. Every sentence adds value. Minor deduction for density—some details could be more succinct, but overall it's efficient for the complexity.

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

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

Given no output schema, the description explains the return structure (opportunities[] fields, partition_check fields, fill check fields). It covers key behaviors (semantic anchor, partition filter, fill check) and error indicators (skipped_low_similarity, placeholders_filtered). However, it lacks details on error conditions (e.g., invalid event slug) or rate limits. Still, it is remarkably complete for a complex tool.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds rich meaning: for 'event', it specifies the format (slug or URL) and explains the inner workings (walks child markets, checks date-axis/threshold-axis ordering, computes partition_check). For 'topic', it describes cross-event scanning and the Jaccard similarity requirement. This goes far beyond the schema's one-line 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) with clear use cases, and the verb 'find' and resource 'arbitrage opportunities' are specific. The description is unique among siblings (e.g., polymarket_edges, polymarket_fill_risk) and does not overlap.

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: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains what each mode does and when to use them. It also states when not to trade ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it') and references sibling polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral detail: internal models (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure (by_segment, _diagnostics), caching ('Cached 1h at the KV level'), and tradeability knobs. No contradiction with annotations.

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

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

The description is long but efficiently structured: starts with purpose, then three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with inline technical details, followed by response top-level and diagnostics. Some details (e.g., specific alpha values, gate parameters) could be considered excessive, but every sentence earns its place given the tool's complexity.

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

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

Given 9 parameters, no output schema, and complex internal logic, the description is exceptionally complete. It covers all three opportunity segments, their model families, tradeability knobs, response structure (including diagnostics and Fed candidates), and caching behavior. No gaps for an agent to safely invoke the 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 detailed parameter descriptions (e.g., min_edge_pp: 'Minimum |edge| in percentage points to include (default 0.5). Edge is evaluated NET of slippage.'). The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their purpose (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'). While baseline is 3, the added grouping and rationale elevate it to 4.

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

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

The description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and explicitly targets the use case 'what should I bet on today'. This clearly distinguishes it from siblings like polymarket_arbitrage (specific arbitrage) and polymarket_edge_tracker (tracking).

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

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

The description provides clear context ('agents discover opportunities without paging hundreds of markets') and implies when to use (for daily edge discovery). However, it does not explicitly state when not to use or name alternatives, missing the opportunity to guide agents away from inappropriate tools.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: it reads from daily snapshots, computes decay from edge_pp_net using daily closes, explains signed vs. absolute values, and notes snapshot gaps. It also clarifies limitations like TTL and snapshot start date, providing a rich behavioral profile.

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

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

The description is front-loaded with the core question, making its purpose immediately clear. It is detailed but well-structured into logical sections (arguments, response fields, limits). While not minimal, every sentence earns its place by adding necessary context without excessive verbosity.

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

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

Despite lacking an output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) and explains each field's meaning and computation. This compensates for the missing schema and provides agents with complete expectations for the tool's output.

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

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

The input schema already covers both parameters (days, window) with descriptions. The description adds value by specifying default values (14 for days, '1wk' for window) and clarifying constraints (max 30 for days, window families). This supplemental information helps the agent use the parameters correctly.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It uses specific verbs ('answers' with the key question) and distinctively positions the tool as analyzing historical edge behavior, contrasting with a single-snapshot view. This strongly differentiates it from sibling tools like 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?

The description explains when to use the tool by framing the trade-off: 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies this tool is for investigating edge history rather than just current edges. However, it does not explicitly name alternatives or state when not to use it, leaving some room for inference.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds detailed behavioral context: walks order book ladder, returns verdict (clean|degraded|cannot_fill), lists specific fields like vwap_fill_price, slippage_pp, and forced_directional_risk. No contradiction with annotations.

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

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

Well-structured with bold mode headers and bullet-like lists. Front-loaded with purpose. However, slightly verbose; could be trimmed while retaining all essential 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?

No output schema, but description comprehensively lists return fields for both modes: single-market returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket returns theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk. Covers edge cases like auto side detection and size clamping.

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 meaning beyond schema: explains the 'auto' default for side in basket mode, interprets size_usd as settlement notional for baskets, and clarifies input expectations for 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 the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and references specific sibling tools (polymarket_arbitrage) to differentiate usage.

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

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

Explicit 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides rationale: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional position.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains when spreads are meaningful or invalid.

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 slightly verbose. It is well-structured with clear sections for modes, response, and safety fields, though could be tightened.

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 fully explains the response format (leg-by-leg prices, spread array, safety fields) and provides sufficient context for correct 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 coverage is 100% with descriptions and examples for all 3 parameters. The description adds context about topic list and overriding behavior, but baseline is 3 since schema already covers parameter meaning.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, differentiating it from sibling tools like polymarket_arbitrage or 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?

The description explains two modes (topic shortcuts and explicit event tickers) and warns that most pre-mapped topics return compatibility warnings. It lacks explicit comparison to alternatives 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 mark as readOnly, idempotent, non-destructive. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and pairing behavior 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, front-loaded with primary action, no extra words. Earning each sentence.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers usage, modes, scoping, and related tools.

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 one optional parameter. Description explains 'omit to list all keys', which reinforces the schema's description but adds no new semantics beyond that.

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 verb (retrieve/list) and resource (saved values/keys). Distinguishes from sibling tools 'remember' and 'forget' by specifying the retrieval action.

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 (look up context stored earlier, avoid re-deriving) and hints at pairing with remember/forget. Does not explicitly list when not to use 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 declare readOnlyHint=true, etc. The description adds behavioral context: it returns source, citation_uri, raw payload, and explains the mark_read flag behavior. 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, front-loaded with purpose, each sentence adds essential information without redundancy.

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

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

Given the 5 optional parameters and no output schema, the description comprehensively covers return fields, filtering options, and usage patterns like polling and alternative REST access.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by providing examples (e.g., type 'sec_8k'), clarifying 'since' as ISO timestamp, and explaining the effect of mark_read.

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

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

The description uses specific verbs ('Pull', 'Returns') and clearly identifies the resource as 'fired events from your subscription feed'. It distinguishes from sibling tools like 'list_subscriptions' which lists subscriptions themselves, not the events.

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

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

The description states that polling works fine for this tool and mentions an alternative REST endpoint for scripts and dashboards. However, it does not explicitly compare it to sibling tools or provide when-not-to-use scenarios.

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, etc.), the description richly details behavioral traits: fan-outs to multiple sources with fallback logic (GDELT preferred, GNews on failure), soft-fail for USPTO due to API sunset, return structure (grouped changes, total count, 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 a single, well-structured paragraph that packs essential information without redundancy. It front-loads with user-facing query examples, then logically flows through sources, parameter details, and output structure. Every sentence adds 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?

Given the tool's complexity (multiple data sources, fallback strategies, parameter syntax), the description is remarkably complete. It covers all aspects: what it does, how it handles failures, return format, parameter options, and a direct comparison to a sibling tool. No output schema exists, but output structure is adequately described.

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% (each parameter documented). The description adds value by explaining `since` with both ISO and relative format examples, clarifying that `type` is limited to 'company', and providing context for `value` (ticker or CIK). Baseline 3 is elevated due to these additions.

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: providing a change feed for a company by aggregating from multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives concrete query examples and distinguishes itself from the sibling tool entity_profile.

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

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

The description explicitly contrasts with entity_profile, stating when to use that instead ('Use entity_profile instead when you want the static profile... regardless of window'). It also provides example queries and typical monitoring instructions ('Use "30d" or "1m" for typical monitoring').

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 idempotentHint=true and destructiveHint=false; description adds scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions—behavioral context beyond annotations.

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

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

Concise, well-structured description with front-loaded main action, no wasted words, and logical flow from purpose to usage to persistence 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?

Complete for a memory storage tool with no output schema: covers purpose, usage timing, storage format, scoping, persistence, and pairing with sibling tools.

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

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

Schema covers 100% of parameters with descriptions; description adds practical naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies value as 'any text' including findings and preferences.

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

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

Description states specific verb 'save' and resource 'data' for reuse, clearly distinguishing from sibling tools 'recall' and 'forget' by mentioning pairing.

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 tells when to use (discover something worth carrying forward), provides storage format (key-value pair scoped by identifier), and contrasts with 'recall' and 'forget' for retrieval/deletion. Also notes authentication-based persistence differences.

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

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

Beyond the read-only, idempotent, and open-world annotations, the description adds valuable behavioral details: identifiers are labeled with their source, unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and LEI/FIGI enrichment degrades gracefully if upstream services fail. These traits are not inferable from annotations alone.

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

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

The description is longer than ideal but each section earns its place: examples, purpose, supported types, and failure behavior are all relevant. It front-loads the core purpose and usage, but the detailed company section could be seen as dense; nevertheless, it remains organized and without 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 the absence of an output schema, the description provides a thorough picture: it explains what identifiers are returned for each type, how unresolved items are handled, and the graceful degradation of enrichment. The tool's complexity is high (multiple upstream sources), and the description covers the key aspects an agent needs to use it correctly.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds value by specifying exact input formats (e.g., '10-digit CIK') and providing concrete examples like 'AAPL' and 'ozempic', plus clarifying how each type affects outputs. This goes slightly beyond schema, but not extensively enough for a 5.

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/official identifiers, with a specific verb ('resolve') and resource ('entity names to identifiers'). It distinguishes itself by explicitly stating 'Use FIRST whenever you have a name but need an ID' and provides examples of supported entity types (company, drug) with detailed output identifiers, differentiating it from sibling tools like entity_profile.

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

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

The description gives clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID,' and explains that it replaces 2-3 manual lookups. It does not explicitly name alternatives or state when-not-to-use, leaving some ambiguity relative to sibling tools like entity_profile, so it falls short of a 5.

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

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

The description explains that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. This adds context beyond annotations which already declare readOnly and idempotent. 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 three concise sentences with no fluff, front-loading the purpose and immediately providing a use case example.

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

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

For a tool with 4 parameters, no output schema, and no nested objects, the description adequately covers purpose, usage, behavior, and return format. It even mentions internal dependency on ai_visibility_check.

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

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

The input schema has 100% parameter description coverage, including details on entities order and context. The description does not add significant new information about parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing it from the sibling ai_visibility_check which handles single entities. The verb 'compare' and resource 'AI visibility across multiple entities' are specific.

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

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

The description explicitly states this is useful for competitive AI-marketing audits and contrasts with a single-entity check by saying 'side-by-side'. However, it does not explicitly state when not to use it or mention alternatives beyond ai_visibility_check.

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

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

Beyond annotations, the description details potential latency ('bundlephobia's first measurement on a new version can take 5-30s'), partial failure handling ('sources_failed will list it if it times out, the rest still returns'), and graceful degradation. 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 well-structured and front-loaded with the core purpose. While it is lengthy, every sentence adds relevant information, and there is minimal redundancy.

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

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

Given no output schema, the description thoroughly explains return values (summary block, per-advisory detail, links, alternative versions). It also covers scope limitations and edge cases like partial failures, making it complete for the tool's complexity.

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

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

With 100% schema coverage, the description adds value by clarifying that scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. This augments 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 clearly states the tool's purpose as a composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from siblings by focusing on npm ecosystem and combining multiple data sources.

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

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

Explicitly specifies when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds technical details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. This far exceeds annotation coverage and reveals critical behavioral traits.

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 convey purpose, usage, and technical details. Front-loaded with core purpose. Could be slightly more structured by separating usage from implementation, but 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?

No output schema, but description explains return values: 'top-N passages with character offsets and similarity scores.' Also covers truncation, pairing with sibling tools, and maximum input size. Fully complete for an agent to invoke correctly.

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

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

Schema has 100% coverage with descriptions. Description adds value by providing examples for query (e.g., 'supply-chain risk') and clarifying constraints for text (max 200K chars) and limit (1-20, default 5). Enhances understanding beyond 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?

Description clearly states 'semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by contrasting with cramming text into prompts and pairing with ask_pipeworx_grounded, showing unique value.

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?

Tells when to use: 'when the record is too big to cram into the prompt — search_within saves context.' Mentions pairing with ask_pipeworx_grounded, providing context for alternative usage. No explicit when-not-to-use, but clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds that it uses the DataForSEO API and provides the output structure (anchor texts with counts), which adds context beyond the annotations.

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

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

The description is concise with one explanatory sentence, a natural language query, and an example. The query phrase is slightly redundant but not harmful. Overall well-structured and 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?

No output schema is provided; the description hints at output fields but does not specify structure or pagination. For a tool with 4 parameters and moderate complexity, the description is adequate but leaves gaps in output expectations.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds an example but no new semantic information beyond what the schema 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 it returns anchor-text distribution with backlink and referring-domain counts, using a specific verb phrase. It distinguishes from siblings like seo_backlinks_list (lists backlinks) and seo_backlinks_summary (summary stats) by focusing on anchor texts.

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?

No explicit guidance on when to use this tool versus other SEO backlink tools. The description does not mention alternatives or scenarios where this tool is preferred.

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, destructiveHint. Description adds details about returned data (monthly history, new/lost referring domains, rank) and a usage context. No contradictions. It doesn't mention rate limits or auth beyond schema, but the annotations cover safety adequately.

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 plus a concise example. Purpose is front-loaded and informative. Every part earns its place; 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 no output schema, the description specifies the return data: monthly history of backlinks, new/lost referring domains, and rank. All parameters are covered in schema. For a simple historical data tool, this is complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds an example and mentions date range, but no additional meaning beyond what the schema 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?

Description clearly states the tool retrieves monthly backlink history for a domain, including new/lost referring domains and rank. It uses specific verbs ('Backlink growth over time') and distinguishes from siblings like seo_backlinks_list, seo_backlinks_summary, seo_referring_domains.

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

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

The description includes an example and a question ('Is this domain gaining or losing links') that implies use, but does not explicitly state when to use this tool versus siblings like seo_backlinks_list or seo_backlinks_summary. No when-not or 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=true, idempotentHint=true, and destructiveHint=false. The description adds the data source (DataForSEO) and lists returned fields, but does not substantially expand on behavioral traits beyond 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?

Extremely concise: two sentences plus a code example. The first sentence immediately states purpose and outputs. Every element serves a purpose with no 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?

Adequately covers purpose and outputs for a list tool. Mentions returned fields and provides an example call. Lacks information on pagination or rate limits, but given the tool's simplicity, the description is mostly 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%, so the schema already documents all five parameters. The description provides an example call and restates some parameter purposes, but does not add new semantic meaning beyond what the schema offers.

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 returns the actual list of linking pages with specific fields (source domain, anchor text, dofollow flag, dates). Distinguishes from sibling tools like seo_backlinks_anchors or seo_backlinks_summary by specifying it's the list of linking pages. The phrase 'Who links to this site' provides additional context.

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?

No explicit guidance on when to use this tool versus siblings such as seo_backlinks_anchors, seo_backlinks_history, or seo_backlinks_summary. The description includes an example but lacks context for selection criteria.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the data source (DataForSEO) and providing an example call, but does not disclose potential limitations like rate limits or cost implications. Overall, it complements the 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?

The description is concise, consisting of one sentence plus an example. It immediately states the purpose and includes a practical code snippet. While concise, the example adds slight length, but overall it is well-structured and 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?

Given the tool has no output schema, the description sufficiently explains what the tool returns (list of key metrics). It covers the essential aspects for a summary tool, including target parameter and API auth key. No gaps in required information are evident.

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

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

The input schema already provides clear descriptions for all parameters (100% coverage). The description adds an example demonstrating usage but does not introduce new meaning beyond what the schema offers. The baseline of 3 is appropriate.

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

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

The description clearly states it provides a backlink profile summary, listing specific metrics like total backlinks, referring domains, domain rank, dofollow/nofollow split, and spam score. It distinguishes itself from sibling tools (e.g., seo_backlinks_list, seo_backlinks_anchors) by focusing on the 'how strong is this domain's link profile' overview.

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 identifies the tool as a summary overview for assessing link strength and provides an example. However, it does not explicitly state when to use this tool versus its siblings (e.g., for detailed backlinks list or anchor text analysis), though the name and content imply the appropriate 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds context about returned fields but does not disclose other behaviors (e.g., rate limits, API key usage) that aren't already in schema. 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 two focused sentences plus an example. It front-loads the purpose and is free of redundant or irrelevant information.

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

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

Despite lacking an output schema, the description clearly explains what is returned (rank, backlink count, spam score). Annotations indicate read-only and open world, making the description complete for a 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%, so the description's main added value is the usage example. The description does not add significant meaning beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the tool returns referring domains for a target, with specific fields (rank, backlink count, spam score). It uses specific verb and resource, and the name distinguishes it from sibling SEO tools.

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

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

The description implies usage ('Which sites link to this domain') and provides an example, but does not explicitly state when to use this tool over siblings like seo_backlinks_list or seo_backlinks_anchors. No when-not or alternatives are given.

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

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

The description adds behavioral context beyond annotations: persistence requirement, type-specific parameter details, delivery constraints (webhook signing, auto-disable after failures), and communication limits. Annotations indicate a non-readOnly, idempotent, non-destructive write; the description confirms this and adds valuable details about OAuth requirement and delivery behavior.

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

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

The description is concise and well-structured, with the main action and requirement stated first. It uses bullet-like formatting for examples and avoids unnecessary words. Every sentence provides meaningful 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?

The description covers the core functionality (three subscription types explained, delivery options detailed). However, the schema includes two additional types ('patent_grant', 'clinical_trial') not mentioned in the description, though their parameters are in the schema. The description could be slightly more complete by noting all supported types, but the schema fills the gap.

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

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

The description adds significant meaning beyond the schema. It provides concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topic) and explains delivery subfields with constraints (SMS verification, webhook signing). Schema coverage is 100%, but the description enriches it with real-world usage context.

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 ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by specifying the creation aspect and supported types.

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 outlines prerequisites ('Requires a Pipeworx OAuth account') and constraints (phone verification for SMS, 10/day cap). While it does not explicitly state when to use this vs. alternatives, the context of sibling tools and the description's focus on creation make usage clear. It provides good guidance on when not to use (anonymous/BYO).

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. The description adds valuable context: it is the onboarding entry point, returns example questions with tool+argument shapes, and does not describe any destructive behavior. 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 front-loaded with alternative question forms, clear and organized. While somewhat lengthy, every sentence adds value. A minor reduction in examples could improve conciseness, but it remains 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?

The description fully explains purpose, usage, and return format (category-bucketed examples with tool+argument shapes). It lacks details on the exact structure of the response, but the tool is simple with one optional parameter and no output schema. The description is sufficient for an onboarding 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% and the schema describes the parameter (topic with options and behavior). The description reiterates the topic options but adds context about the tool's purpose and the return format, which indirectly helps parameter usage. 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 returns category-bucketed example questions as an onboarding entry point. It uses specific verbs ('returns') and resources ('example questions'), and distinguishes itself from siblings by positioning it as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with no arguments for full spread or pass topic, and names sibling meta-tools as alternatives.

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

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

Annotations already set idempotentHint=true and destructiveHint=false; description adds ownership enforcement and data life cycle (deactivated, not deleted), compensating well beyond minimal annotation info.

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 covering action, constraint, and data effect; no wasted words, front-loaded with purpose.

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

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

For a single-parameter idempotent deactivation tool with no output schema, the description fully addresses how it works, who can use it, and its persistence 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 covers 100% of parameters with clear description for id; description does not add extra meaning beyond schema, but baseline 3 is appropriate as the schema is sufficient.

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 cancels a subscription by id, distinguishes from sibling subscribe/list_subscriptions, and explains ownership enforcement and deactivation vs deletion.

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?

Specifies ownership enforcement (only own subscriptions) and hints that the id comes from subscribe, but does not explicitly contrast with other cancellation methods or when not to 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?

Beyond the readOnly/idempotent annotations, the description reveals the dual-path architecture (SEC EDGAR+XBRL vs grounded pipeline), enumerates all possible verdicts, and clearly defines the critical distinction between could_not_verify and unsupported. It adds a direct caller directive not to treat could_not_verify as evidence, which is essential for correct interpretation. No contradiction with annotations.

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

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

Though lengthy, every sentence carries operational weight. The structure is logical: trigger phrases → when to use → routing → verdicts → error semantics → efficiency gain. The 'IMPORTANT for callers' flag highlights critical caveats without burying them. No filler or redundancy.

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

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

For a complex tool with no output schema, the description provides complete operational context: input types, internal routing, full verdict enumeration, error semantics, and behavioral cautions. It covers both financial and non-financial paths and explains the meaning of each verdict, making it self-sufficient for an agent to invoke and interpret results correctly.

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

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

The schema covers both parameters (100% coverage), so baseline is 3. The description adds meaningful semantics: tolerance_pct's override behavior, the default derived from claim wording capped at 5, and use-case guidance (1–2 for hallucination detection). claim is enriched with concrete examples and the expected natural-language format.

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

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

The description opens with concrete trigger phrases ("fact check", "verify the claim that") and explicitly states its function as natural-language claim verification against authoritative sources. It clearly distinguishes from sibling tools by noting it replaces 4–6 sequential calls and details the specific financial versus non-financial scope.

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 an explicit when-to-use rule ('Use whenever the agent needs to check whether something a user said is factually correct') and contrasts itself with a multi-step alternative. However, it lacks an explicit 'when not to use' case, though the broad 'ANY OTHER factual claim' coverage implies it's always appropriate for factual checks.

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