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 establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context by revealing that it is a meta-router that auto-fills arguments, dispatches to thousands of tools, and returns stable citation URIs. This goes beyond the annotations, though it does not discuss potential latency or delegation side effects.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and packs in domains, trigger phrases, and examples efficiently. It loses a point for the redundant closing phrase 'START HERE for most questions — for most questions, START HERE,' which adds noise without new information.

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

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

For a broad router tool with no output schema, the description covers what it does, when to use it, what it returns, and how it behaves. It is complete enough for an agent to decide to invoke it. It lacks any caveats or fallback conditions, but that is a minor gap given the tool's straightforward single-parameter interface.

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

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

The input schema fully describes all six aliases and the 'question' parameter, so the baseline is 3. The description supplies example natural-language queries and says the tool 'fills arguments,' which is mildly helpful, but it does not add substantive semantic detail about the question parameter beyond what the schema already provides.

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

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

The description clearly states what the tool does: it routes factual questions to one of 5,743 tools across 1500 sources and returns a structured answer with pipeworx:// citation URIs. It positions itself as a first-line resource for authoritative data, which distinguishes it from web search. However, it does not explicitly differentiate siblings like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of full sibling distinction.

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

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

The description gives strong positive usage signals: 'PREFER OVER WEB SEARCH', explicit trigger phrases like 'what is', 'look up', 'get the latest', and several concrete examples. It also says to use it 'even if web search could also answer it,' which is a clear exclusion for web search. It does not, however, state when to prefer or avoid alternative sibling tools, so the when-not-to-use guidance is 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?

The description goes well beyond the annotations by disclosing that candidate routing improvements may be enabled live, that none is currently active, that the tool currently matches ask_pipeworx exactly, and that results are compared against the stable router. It also clarifies there is no degraded fallback and that this is a full working router, making runtime behavior highly transparent.

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 identity, then explains current behavior, usage, and reliability in a compact, well-structured way. Every sentence contributes useful information, including the status update about the last retired candidate and the reassurance that the tool is fully functional.

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

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

For a tool with no output schema, the description compensates by specifying that the response shape is identical to ask_pipeworx, which is critical for an agent to know what to expect. Combined with annotations covering safety and the description covering routing semantics, current state, and comparison purpose, nothing essential is missing.

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

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

Schema description coverage is 100%, with all parameters being string aliases for the same question input, so the schema already carries the parameter semantics. The description adds the note that arguments are 'the same' as ask_pipeworx, which is useful context but does not meaningfully expand on what each parameter means beyond the schema.

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

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

The description clearly identifies a specific tool: a beta variant of ask_pipeworx that is an identical universal router with the same 5,743 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx and notes its experimental edge, so an agent can tell it apart from siblings immediately.

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

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

The description gives explicit usage context: use it exactly like ask_pipeworx when you want the newest routing, and it notes the current state has no active candidate so it matches ask_pipeworx exactly. It does not explicitly state 'use stable ask_pipeworx for production' as a when-not-to-use condition, but 'beta' and 'experimental edge' strongly imply that distinction.

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

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

Goes far beyond the readOnly/openWorld/idempotent annotations by disclosing the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the full refusal_reason enum with five values, the verbatim-quote evidence contract, and the constraint that extraction uses only tool-result content. Nothing contradicts 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?

Dense but zero-waste: core identity first, then mechanism, then the return/refusal contract, then selection guidance and cost. Every sentence earns its place, and since there is no output schema, the detailed return-shape disclosure is necessary rather than padding.

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 read-only, schema-documented tool: an agent can select it, invoke it, and interpret both success and refusal outputs without guessing. The cross-reference to ask_pipeworx is legitimate given the sibling list, and annotations cover the safety profile.

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

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

Schema description coverage is 100% — the question parameter and all five aliases are documented with type, format, and natural-language guidance in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies; the schema correctly carries the parameter burden.

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

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

Opens with a specific, differentiating identity — 'Hallucination-resistant answer mode for high-stakes reads' — followed by a concrete mechanism: routes across 5,743 tools, fills arguments, fetches data, then extracts the answer using ONLY the tool result. It frames itself against the sibling ask_pipeworx rather than restating the name.

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 names the alternative (ask_pipeworx), the selecting condition ('whenever an answer will be quoted, cited, or acted on'), concrete high-stakes examples (financial, legal, medical, public statements), and the exclusion ('prefer ask_pipeworx for casual lookups') with the cost tradeoff of one extra LLM call. An agent needs zero inference to choose 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 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral disclosure: account/payment requirements, parallelism across 5,743 tools, explicit gaps[] for unanswered facets, contradictions[] returns, semantic excerpting rather than head-truncation, stable citations that are always fetchable, and expected latency ranges. This richly clarifies what happens during execution.

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 nearly every sentence carries load-bearing guidance: account constraints, usage routing, output shape, gap handling, depth semantics, citation behavior, latency. It is front-loaded with the account requirement and the alternative-tool fallback. It loses one point for density: the parenthetical-heavy, run-on style can make it harder to parse in one pass.

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 is exceptionally complete. It explains the findings packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), the behavior of gaps[] (never invented), contradictions[], hop field, citation_uri fetchability, excerpting behavior, timing, and prerequisites. An agent has everything needed to invoke correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the raw schema by explaining the practical difference between depth options: 'quick=3 (single hop)', 'standard=3 (default; adds a gap-recovery hop ... plus a contradictions[] scan)', and 'thorough=6 (paid; adds a full iterative hop ...)'. It also explains that 'question' can be broad/multi-part. Slight deduction because the description doesn't add new information about the question parameter format beyond schema's natural-language note, but the depth elaboration is genuinely useful.

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 1500 STRUCTURED data sources ... in ONE call', and explicitly distinguishes itself from open-web search. It also differentiates from ask_pipeworx by positioning itself for broad/multi-part questions. An agent can clearly identify what this tool does and how it differs from siblings.

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

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

The description gives explicit when-to-use/when-not-to-use guidance: use ask_pipeworx for single lookups, breaking/colloquial current-news topics, or when not signed in. It also details depth-level semantics and the second-hop iteration behavior, so the agent knows exactly which depth to pick and when the tool is appropriate.

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

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

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 mark it read-only/idempotent/non-destructive, so the description doesn't need to restate safety. It adds strong operational context: parallel fan-out, soft-fail sources, sources_used/sources_failed, resolved:false for private companies, and interchangeable type values.

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?

Information-dense and mostly front-loaded with user intents and the core preference directive. The later source-list paragraph is long and somewhat run-on, but every clause carries substantive behavior; only minor trimming would improve it.

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

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

With only two documented parameters and safety annotations present, the description provides everything an agent needs: accepted value shapes, output sections, failure semantics, and source behavior. No output schema exists, yet the returned fields are described in enough detail to interpret results.

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

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

Schema provides 100% coverage of both parameters, including the enum and value-shape descriptions. The tool description reinforces examples and interchangeability, but doesn't need to add meaning because the schema already fully documents 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?

Description names a specific verb and resource: producing a full cross-source profile of a US public company, immediately distinguishing it from single-source lookups and sibling tools like compare_entities or resolve_entity. The examples and 'ONE parallel call' clarify exactly what the tool is for.

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

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

It explicitly states when to prefer it: any holistic 'tell me about X' request, and ALWAYS over chaining single-pack SEC/XBRL/news lookups. It also handles edge cases (private companies) and notes expected empty sections, giving clear invocation 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 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?

Even with read-only annotations present, the description goes far beyond them by disclosing the identical token-overlap matcher, compatibility warning codes, unclassified leg exclusions, skipped comparison counters, the fee disclosure limitation, and the fact that returned pairs can still carry warnings. This is exemplary behavioral transparency for a complex comparison tool.

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 it is densely informative and organized around clear concepts like MODES, RESPONSE, SAFETY FIELDS, and fee disclosures. Every sentence carries operational value, and the core purpose is front-loaded. It could be tightened with bullet formatting, but it earns its length given the tool's complexity and absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining return shape, safety fields, compatibility codes, skipped counters, temporal alignment semantics, and fee limitations. It covers all of these in detail and even manages expectations about how often pre-mapped topics are actually tradeable. Nothing critical appears missing.

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

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

Schema coverage is complete, so the baseline is 3, but the description adds meaningful semantics: it explains that `topic` auto-fetches matching events, that explicit ticker/slug overrides the mapped side, and that both modes run the same matcher with the same disclosures. This enriches the schema without repeating it.

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

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

The opening sentence clearly identifies the tool's purpose: calculating cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing on the same-question constraint and the Kalshi–Polymarket pairing, though it does not explicitly name alternative tools to compare against.

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 explains the two modes of use — `topic` shortcuts versus explicit `kalshi_event_ticker` and `polymarket_event_slug` pairings — and when each is appropriate. It also cautions that pre-mapped topics often return compatibility warnings and that spreads are gross, not net tradeable edges. It does not explicitly steer users toward sibling tools, so it stops short of a 5.

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

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

Annotations already 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?

Annotations already indicate read-only, idempotent, non-destructive. The description goes far beyond: it discloses the cascading internal lookup behavior, graceful degradation if GLEIF/OpenFIGI is unavailable, ambiguity handling (returns figi_candidates, asserts nothing), source labeling, and the unresolved field. It also explains the input format caveat for bonds. This is rich behavioral context that annotations alone cannot convey — no contradiction.

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

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

The description is long and dense, but well-structured with clear paragraphs and lists (supported types, behavior notes). The most critical usage guidance ('Use FIRST whenever...') is front-loaded, and every sentence adds value by explaining a scenario, caveat, or behavior. Slightly verbose but not wasteful; earns its length.

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

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

Despite no output schema, the description explains what is returned (identifiers, unresolved items, figi_candidates) and the behavior around each. It covers edge cases (ambiguity, unavailable sources, non-equity instruments) and input requirements thoroughly. For a tool with this complexity (cascading lookups, multiple sources), the description is complete and leaves no critical 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?

Schema description coverage is 100%, but the description adds substantial meaning: it explains acceptable formats for 'value' (ticker, CIK, name for company; brand/generic for drug), illustrates with examples, and provides a critical warning about not including security-class words for bonds. It also clarifies the 'type' enum semantics. This goes beyond the schema's basic type 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 verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and explicitly differentiates from siblings by explaining that it produces identifiers other tools require as input. It covers supported types (company, drug) and describes the cross-source identity spine, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains specific scenarios (bonds, drug names) and provides a critical input caveat (pass entity name only). However, it does not explicitly state when not to use the tool or name alternative tools, though the phrase 'replaces 2-3 manual lookups' implies the alternative is manual lookup. Slightly lacking in exclusions but strong on positive usage.

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

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

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.