Askdata Xk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: default model is free, Anthropic requires a BYO key with direct payment, and it describes the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 three sentences, each earning its place: first sentence covers the core action and return type, second sentence gives parameter details and cost implication, third sentence lists use cases. No filler, front-loaded with key information.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description adequately explains the return format (per-model object + combined view), covers all parameters, and provides usage scenarios. No gaps given the annotations and schema richness.

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 meaning beyond schema: it explains the default model for the 'models' parameter, states that _apiKey is passed through to Anthropic and entails direct payment, and clarifies that 'context' helps disambiguate. This provides useful operational guidance.

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 explicitly that the tool probes LLMs and scores visibility (0-100) per model, using specific verbs like 'probe' and 'score'. It distinguishes from siblings (e.g., ask_pipeworx, entity_profile) by its unique focus on visibility scoring across multiple models.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains when to use the default model vs. Anthropic with _apiKey. However, it does not explicitly list when not to use this tool or mention alternatives among 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 readOnly, openWorld, idempotent, non-destructive, which align with the description. The description adds valuable behavioral context: it routes to 5,566 tools across 1,462 sources, returns stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. It also hints at limitations by contrasting with the 'hallucination-resistant' grounded version. Minor deduction for not addressing potential timeouts or error handling, but it surpasses the baseline.

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 packed with high-value guidance: usage priority, examples, and alternative routing. Front-loading with 'PREFER OVER WEB SEARCH' immediately captures the tool's purpose. Slightly wordy in places, but every sentence adds context, making it acceptable for a tool of this breadth.

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

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

Given the tool's complexity and lack of an output schema, the description covers citations, source routing, and default behavior well. It doesn't detail return formats or error handling, but for a dispatch tool like this, the provided examples and scope sufficiently set expectations. The description is comprehensive without being bloated.

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 six parameters, five of which are aliases for 'question'. The main parameter's description is clear and notes it accepts aliases. The tool description reinforces the natural language nature but does not add extra beyond the schema. Per rubric, baseline 3 is appropriate when schema covers everything; this is met.

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

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

The description clearly states the tool answers questions about current/historical data with citations, listing concrete domains (SEC, FDA, FRED, etc.). It includes a strong 'PREFER OVER WEB SEARCH' directive and distinct use cases, separating it from siblings like ask_pipeworx_grounded and deep_research. Specific verbs like 'routes', 'returns', and 'START HERE' make 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?

Provide explicit when-to-use instructions ('Use whenever the user asks...'), concrete examples, and direct comparisons to alternatives ('Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research'). This is a model of usage guidance, covering both when and when not to use the tool.

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

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

Beyond the annotations (read-only, idempotent), the description adds critical behavioral context: it is a full working router (not a fallback), may have routing improvements enabled live, and currently matches ask_pipeworx exactly. It also discloses the comparison against the stable router, which is not evident from annotations. This goes beyond the structured metadata.

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 few sentences long, each adding value: beta status, current state, usage guidance, and a reassurance that it is a full router. It is front-loaded with the main purpose and avoids redundancy, though it could be slightly more compact by trimming the last sentence. Overall well-structured and efficient.

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

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

Given the complexity of a universal router with 5,566 tools, the description provides sufficient context by linking to ask_pipeworx for details and clarifying the beta nature. It mentions the same response shape and that it is a full working router. It doesn't elaborate on specific tool usage, but relies on ask_pipeworx's documentation, which is acceptable for an alias-like tool. No output schema is present, so no need to describe return values.

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

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

The schema already provides 100% coverage, with a clear description of the question parameter and its aliases. The description only says 'same arguments' as ask_pipeworx, which is a pointer but adds no new semantic detail beyond what the schema states. Thus it meets the baseline for high schema coverage but does not elevate 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 description clearly identifies the tool as a beta version of ask_pipeworx, explaining it is an identical universal router with the same 5,566 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements, making its purpose specific and unambiguous.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide merges, providing clear context for selection. While it doesn't explicitly say when NOT to use it, it implies the stable version for non-experimental needs, and mentions the sibling ask_pipeworx as the reference.

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

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

The description adds significant behavioral detail beyond the annotations: the explicit refusal mechanism with the exact refusal_reason enum, the success payload structure including the `refusal_reason:null` field, and the cost implication. It describes what happens when the data doesn't directly answer (explicit refusal rather than fabrication). The annotations declare readOnlyHint:true and the description seems consistent with this — the tool fetches data without mutating state, and the description's behavior (using tool results only) aligns with read-only semantics.

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

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

The description is information-dense but long — four sentences covering purpose, usage, behavioral contract, and cost trade-off. Every sentence earns its place, and the payload structure is communicated compactly. The success/failure payloads are described in a compact inline JSON-like notation. Loses a point for being verbose relative to alternatives that front-load the core purpose in a single tagline.

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 6 parameters (5 aliases), 100% schema coverage, and strong annotations, the description covers the key gaps: the exact success/refusal payload structure, the failure modes via refusal_reason, and the cost trade-off. The return value is fully specified inline without an output schema. Slight deduction because the refusal_reason enum is already visible in the description but the downstream implications (e.g., how the agent should interpret each error code for retry) aren't elaborated — though this may be beyond scope given the richness provided.

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 its 5 aliases are documented directly in the schema. The description goes beyond this by clarifying the tool accepts a natural language question and that it will be routed through the same pipeline as ask_pipeworx. However, the description doesn't need to add parametration value since the schema is fully self-documenting. 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 uses a specific verb phrase ('Hallucination-resistant answer mode') and clearly identifies the resource ('reads' via the same routing as ask_pipeworx). It explicitly distinguishes the grounded mode from its sibling ask_pipeworx, noting it 'picks the right tool from 5,566 across 1462 sources' and extracts answers only from tool results. The opening label 'Hallucination-resistant answer mode for high-stakes reads' is specific and differentiates it from alternatives.

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

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

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on'), when not to ('for casual lookups' prefer ask_pipeworx), and names the alternative ('prefer ask_pipeworx'). It even notes the cost trade-off ('Costs one extra LLM call vs ask_pipeworx') which directly informs the use-vs-alternative decision.

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 extensive behavioral context beyond the annotations, including how it resolves markets, classifies bets, fans out to data sources, handles errors (low-confidence, closed markets, wide spreads), and returns response shapes. It is consistent with the readOnlyHint annotation and provides rich detail about internal 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 thorough but verbose, spanning over 500 words. It is well-structured with sections and examples, and the first sentence provides the core purpose. However, some details could be condensed without losing value, making it slightly less concise than optimal.

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

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

Given the tool's complexity (multiple classifiers, fan-out, resolution, evidence) and absence of an output schema, the description is remarkably complete. It covers input formats, resolution logic, response structure, error conditions, cancellation rules, and safety mechanisms. An agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra beyond the schema's parameter descriptions. For example, the market parameter's ability to accept slug, URL, or question text is already in the schema. The depth parameter's defaults and include_raw's summary behavior are also in the schema. The description does not add significant new semantic information.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and provides concrete use cases. It distinguishes itself from sibling tools by its comprehensive single-call research approach, though it doesn't explicitly name alternatives.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides guidance on when to use but does not explicitly say when not to use alternatives. The detailed safety conditions and edge cases also help guide usage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: for companies, it pulls latest 10-K data from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drugs, it pulls FAERS adverse event counts, FDA approval counts, and active trial counts. It also mentions sorted output and citation URIs.

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

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

The description is comprehensive but slightly lengthy. It is well front-loaded with example triggers and immediately states the core functionality. Every sentence adds value, though a minor redundancy could be trimmed.

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

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

Given the simplicity (2 parameters, no output schema), the description is remarkably complete. It covers data sources, edge cases (off-calendar fiscal years), sorting, and the number of sequential lookups it replaces. No gaps remain.

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

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

Schema coverage is 100% with both parameters described. The description adds valuable context: explains that 'values' for company type are tickers/CIKs (with examples like AAPL, MSFT) and for drug type are names (with examples like ozempic, mounjaro). It clarifies the format and constraints.

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 starts with example queries ('Compare X and Y', 'X vs Y', etc.) and explicitly states it does side-by-side comparison of 2–5 companies or drugs. It clearly distinguishes from sequential single-pack lookups, 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides criteria for when to use (comparing companies or drugs). It also explains how results are sorted (by primary metric) for queries like 'largest'/'most'.

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

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

The description discloses the tool's long execution time (15-60s, up to 90s for thorough), the need for an account (free, with paid plan required for some features), the fact that it returns gaps[] for unanswered facets and never invents findings, the presence of contradictions[] for deeper depths, and the behavior of semantically excerpting large records. This goes well beyond the annotations (which already indicate readOnly, openWorld, idempotent) and adds crucial behavioral context without 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?

Although the description is long, it is information-dense and well structured, with clear sections for account requirements, alternative use cases, depth semantics, and behavioral guarantees. Every sentence adds meaningful value, and the key points (account, alternative, non-web) are front-loaded. It's not excessively verbose given the complexity of the tool, though a slight trim could improve scannability.

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

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

For a tool with only two parameters (both fully described in the schema) and no output schema, the description still explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field) and important constraints (citation_uri present only when fetchable). It also covers pricing/account requirements. It is complete enough for an agent 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?

The schema already covers 100% of parameter semantics: it describes question as a natural language query and depth's enum values with details. The description adds context by explaining the hop behavior and gap recovery for each depth level, which enhances understanding beyond the schema. However, the schema's descriptions already match the description's depth explanations, so the description only adds a little extra (e.g., the 'never invented' guarantee). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'multi-source research across Pipeworx's 1462 STRUCTURED data sources' in a single call, and distinguishes it from open-web search and from siblings like ask_pipeworx. It names specific use cases and explicitly contrasts with alternatives, which is excellent for an agent.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it specifies that deep_research is best for broad/multi-part questions over structured data, while single lookups or breaking news should use ask_pipeworx. It also explains depth levels (quick/standard/thorough) and their trade-offs, 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states that 'each result is ready to call directly, no second schema lookup needed.' This fully discloses the behavior and output format.

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

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

The description is fairly long but well-structured: it starts with the core purpose, lists domains, describes output, and ends with usage advice. Every sentence adds value; however, it could be slightly more compact without losing information. Overall, it is appropriately sized for a complex meta-tool.

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

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

Given the tool's complexity (6 parameters, many aliases, no output schema), the description covers purpose, usage, output format, parameter semantics, and examples. It compensates for the lack of output schema by describing the return value in detail. It is fully complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining that the 'query' parameter accepts natural language descriptions and provides aliases (task, q, description, search). It includes concrete examples like 'analyze housing market trends' and 'look up FDA drug approvals,' which go 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 the tool's purpose: 'Find tools by describing the data or task.' It provides a broad list of domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by advising to call it 'FIRST when you have many tools available and want to see the option set.' This makes the purpose specific and differentiated.

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

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

The description includes explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implicitly tells when not to use (when you already know the tool) but does not list alternative tools for specific domains. The usage advice is clear and helpful.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich context: fans across multiple sources, specifics of returned data, patent API sunset and soft-fail, news fallback mechanism. No contradictions with annotations.

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

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

The description is somewhat lengthy but well-structured, starting with example queries, then usage guidance, then detailed outputs and caveats. Every sentence adds value; however, the examples could be trimmed slightly for conciseness.

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

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

Given the complexity of the tool (multiple sources, no output schema), the description is remarkably complete. It details all output fields, data sources, fallback mechanisms, and limitations, enabling the agent to understand behavior without needing an output schema.

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

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

Schema coverage is 100%, baseline 3. The description adds significant semantic context: type is only 'company', value must be ticker or zero-padded CIK, names are not supported, and it references resolve_entity as a prerequisite. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing specific outputs and data sources. It distinguishes itself from sibling tools by explicitly preferring this over chaining multiple single-pack lookups, and notes the name limitation, directing to resolve_entity.

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

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

The description explicitly guides when to use this tool ('when the user asks for a holistic view') and what to avoid ('chaining single-pack lookups'). It also states what not to pass (names) and provides an alternative tool (resolve_entity) for names.

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

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

Annotations already specify destructiveHint=true and idempotentHint=true. Description adds no additional behavioral context beyond 'Delete'.

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

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

Two concise sentences that front-load the action and include usage rationale. No unnecessary 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?

Sufficient for a simple tool with one param, no output schema. Covers purpose, usage, and sibling relationship.

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 key parameter with description. No extra semantic value added by description beyond what schema provides.

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

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

Description explicitly states 'Delete a previously stored memory by key' - clear verb+resource. Distinguishes from siblings 'remember' and 'recall' by action type.

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

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

Provides explicit when-to-use scenarios: 'stale context, task done, clear sensitive data'. Also advises pairing with remember and recall.

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

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

Annotations already indicate non-destructive, idempotent, read-only behavior. Description adds process details (fetches page, extracts title/description/key links, emits standard markdown) and output format, providing full transparency without contradiction.

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

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

Two well-structured sentences: first sentence states purpose and outcome, second sentence elaborates on process, output, and use cases. Every sentence is informative 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?

Despite no output schema, the description fully explains return value (llms.txt markdown text) and optional parameter. With rich annotations and clear process, it provides complete contextual information for the 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 both parameters. The description adds meaning by explaining the output ('single text blob') and the process (extraction from URL), going beyond the schema's basic definitions.

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

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

Description clearly states the tool generates a production-ready llms.txt file from any URL, specifying the verb, resource, and scope. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

Explicitly lists three use cases (indexing client site, drafting own project, auditing competitor), helping the agent understand when to use. Lacks explicit when-not-to-use or alternative tools, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Beyond that, the description adds that only active subscriptions are returned by default and lists return fields, which is useful behavioral context.

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

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

Two sentences, no wasted words. Purpose and usage guidance 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?

Given no output schema, the description lists return fields. Annotations cover safety. The simple parameter is explained. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100% (parameter include_inactive is described). The tool description reinforces the default of active only but adds no new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by listing rather than modifying. The return fields are also specified.

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: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and suggests alternatives (subscribing/unsubscribing).

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

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

The description discloses behavioral traits beyond the annotations: it explains that filing returns a claim_token, that passing it back later retrieves resolution status, and that it is rate-limited to 5 per identifier per day and free (doesn't count against quota). It also advises not to paste the end-user's prompt. These details add significant context not captured by 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 a single paragraph, but every sentence serves a purpose—covering purpose, usage cases, exclusions, message guidance, claim_token semantics, rate limits, and follow-up. It is front-loaded with the core action and flows logically from main purpose to supporting 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?

The tool has no required parameters and a non-trivial dual mode (submit vs. check token), and the description explains both modes clearly. It covers the full workflow, constraints, and expected behavior, making it fully self-contained for an agent to invoke correctly.

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

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

Although schema coverage is 100%, the description enhances parameter understanding by showing how claim_token should be used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This goes beyond the raw parameter descriptions.

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

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

The description uses a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates itself from sibling tools like ask_pipeworx and discover_tools by focusing on feedback submission rather than research or search. The title 'Send Pipeworx Feedback' reinforces the purpose.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' — directing users to file with other MCP servers instead. This is model 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 safe, read-only, idempotent. Description adds caching (5min-1h), data source (CF analytics-engine, no PII), and self-aggregating nature, going 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 with bullet-like use cases, front-loaded with main result. Every sentence adds value with 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?

Tool has only one optional parameter and no output schema, but description specifies return values (top tools, top packs, total call volume) and caching. For a simple tool, it's fairly complete.

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

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

Schema coverage is 100% with enum. Description adds interpretation: shorter windows show hot items, longer windows show steady-state demand, adding meaning beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. Uses specific verbs and resources, and is distinct from sibling tools like discover_tools.

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

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

Lists three explicit use cases and describes window parameter behavior for different timeframes. Lacks explicit when-not-to-use or alternatives, but provides solid contextual 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 indicate readonly, open-world, idempotent, and non-destructive. The description adds rich behavioral context: partition checks, semantic anchors (Jaccard similarity), partition filters (placeholder slugs), fill checks against CLOB depth, and warnings about unrealizable edges. 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 lengthy but well-structured: it starts with the general purpose, then details each mode, and adds technical aspects like semantic anchors and fill checks. Every sentence provides necessary information, though some redundancy could be trimmed for perfect conciseness.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check in event mode). It covers all modes, edge cases (placeholder filtering, low similarity skipping), and actionable advice (do not trade if realizable_edge_pp <= 0). The tool's complexity is fully addressed.

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

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

Schema description coverage is 100% with good descriptions for both optional parameters. The description goes beyond the schema by adding usage context, examples, and detailed explanations of what each mode returns. It clarifies that event mode is recommended for specific markets and topic for cross-event scanning.

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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic), each with a specific use case, and the tool stands out from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use no arguments (trending_scan), event (single event slug), or topic (cross-event scan). It explains trade-offs, such as cross-event mode catching patterns single-event misses, and provides a warning about not trading when realizable_edge_pp <= 0. It also references a sibling tool (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?

Beyond annotations (readOnlyHint=true, etc.), the description details model families, edge metrics, slippage assumptions, caching ('Cached 1h at the KV level'), and diagnostic fields. This provides comprehensive behavioral context without contradicting 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 the core purpose in the first sentence. It is lengthy but well-structured, covering output segments, response fields, knobs, and diagnostics in a logical order. Every part adds necessary detail.

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

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

With no output schema, the description fully explains return values (by_segment, diagnostics, edge fields) and model behaviors. It covers all essential aspects for using the tool, including parameter interactions and segment logic.

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 parameter descriptions in the schema. The description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their role, but most parameter meaning is already captured in the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return) and resource (Polymarket markets), and distinguishes it from siblings by focusing on model-driven and structural arbitrage opportunities.

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 sets context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' indicating ideal use cases. However, it does not explicitly specify when not to use the tool or mention alternatives such as polymarket_arbitrage.

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, openWorldHint, idempotentHint), the description adds critical behavioral details: data source (daily snapshots), limitations (60-day TTL, snapshot gaps), and computational details (decay from daily closes). 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 dense and informative, but somewhat verbose with response details and limits. The first sentence effectively states purpose. While not overly long, it could be slightly more structured without losing clarity.

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

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

The description thoroughly explains the complex response format (tracked, expired, snapshot_dates) and limitations (60-day TTL, snapshot gaps). Given the lack of output schema, the description compensates fully, making the tool's behavior and output clear.

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 context for 'days' (default 14, max 30) and 'window' (default 1wk), but does not significantly expand on the schema descriptions. It matches the schema closely, providing minimal additional value.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current 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 provides strong context for when to use the tool, explaining the importance of edge age in trading decisions. However, it does not explicitly mention alternatives or when not to use it, missing a small opportunity for clarity.

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, open-world, idempotent, and non-destructive. The description adds rich behavioral details: ladder walking, return fields like slippage_pp, thin_legs, forced_directional_risk, and the warning about basket partial fills. 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 front-loaded with the core purpose and uses clear structuring (SINGLE-MARKET, BASKET). While somewhat lengthy, the complexity of two modes and risk warnings justifies the detail. 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 fully explains return values for both modes, including verdicts, thin legs, and forced_directional_risk. It also covers edge cases (cannot_fill verdict) and risk warnings, making it 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?

The input schema has 100% coverage, but the description adds significant meaning: explains mode selection via market vs event, default side logic in basket mode, and interpretation of size_usd (spend vs target proceeds vs settlement notional). This goes well beyond the schema.

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

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

The description states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage by positioning itself as a prerequisite check.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of not using it, such as partial baskets creating unhedged directional positions.

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

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

Annotations already indicate readOnly and idempotent, but the description adds extensive behavioral context: compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal_alignment checks, and detailed counters for skipped comparisons. No contradiction with annotations.

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

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

The description is well-structured with clear headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with purpose. However, it is somewhat verbose with enumerated warnings and could be tightened without losing essential information. Still, it efficiently uses paragraphs to organize complex details.

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

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

Given the tool's complexity (3 parameters, no output schema), the description fully covers all necessary aspects: modes, response structure, safety fields, and edge cases. It leaves no ambiguity about how to invoke or interpret results, making it complete for agent use.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds value by explaining the relationship between 'topic' and the explicit tickers (overriding behavior) and listing all topic shortcuts explicitly. This goes 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 computes 'cross-venue spread' between Kalshi and Polymarket for the same resolving question, with specific modes (topic shortcuts or explicit tickers). This distinguishes it from siblings like 'polymarket_arbitrage' which focuses on a single venue.

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

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

The description explicitly explains when to use each mode (topic shortcuts for quick access vs explicit tickers for custom pairs) and what to expect in results, including warnings that most pre-mapped topics are not tradeable. It also describes when to use alternative approaches implicitly by explaining compatibility conditions.

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 readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the HTTP method (POST), the response format, and the size limitation (10,000 cells). No contradictions with annotations are present.

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

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

Two concise, information-dense sentences. The first sentence front-loads the purpose, and the second provides essential format and constraint details. No extraneous content.

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

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

While the description mentions the response format 'json-stat2' and the size cap, it does not detail the response structure, error states, or the expected behavior for edge cases. For a tool with no output schema and nested parameters, more completeness could be beneficial.

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 a detailed example and descriptions for both parameters. The description reiterates the body format and adds the limitation hint, but does not significantly augment the schema's meaning given 100% schema coverage.

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

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

The description clearly states the action: 'POST a PxWeb query to a Kosovo ASKdata table' and specifies the output format 'json-stat2'. It is specific about the resource and verb, and subtly differentiates from sibling 'table_meta' by suggesting its use for narrowing selections.

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 instructions on the required body format and the cap of 10,000 cells are given. It references 'use codes from table_meta' to narrow selections, providing clear context on how to use the tool effectively. However, it does not explicitly state when not to use this tool versus alternatives like 'search_within'.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds transparency about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains behavior when key is omitted (list all keys). 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 paragraph of three sentences, front-loaded with the main action. Each sentence adds value: the action, use case, and scoping. No wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers main usage, scoping, and pairing with siblings. It is fully adequate given the tool's complexity and available annotations.

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

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

Schema coverage is 100% with a single 'key' parameter fully described. The description only restates that omitting the key lists all keys, which the schema already conveys. No additional semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' The verb 'retrieve' and resource 'saved values' are specific, and it distinguishes itself from sibling tools like 'remember' and 'forget' by explaining its complementarity.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget. While it doesn't explicitly state when not to use it, the sibling list includes alternatives, and the description implies its appropriate use case.

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 mark readOnlyHint=true, but description discloses that setting mark_read:true flags events as read, a side-effect. This adds behavioral context beyond annotations, though it may slightly contradict readOnlyHint.

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

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

Four sentences, no fluff, front-loaded with purpose. Efficiently conveys key 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?

Covers return fields, filtering, read state management, and alternative access. No output schema, but description gives enough structure for agent usage. Lacks explicit mention of default limit.

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

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

Schema coverage is 100% with detailed descriptions. Description adds an example for type ('sec_8k') but largely restates schema. Adequate but not significantly additive.

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 pulls fired events from a subscription feed, specifying the verb 'pull' and resource 'fired events'. It distinguishes this from sibling tools like list_subscriptions by focusing on event retrieval.

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 usage context: filtering by type and since, using mark_read to manage read state, and mentions an alternative GET endpoint for scripts/dashboards. Does not explicitly exclude use cases but gives sufficient guidance for typical 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 goes well beyond annotations by revealing the fan-out to multiple APIs (SEC EDGAR, GDELT→GNews fallback, USPTO), the fallback logic (GDELT preferred, GNews on rate-limit or 5xx), and soft-failure conditions (USPTO API sunset May 2025). It also mentions the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). Annotations already mark it read-only and idempotent, so there is no contradiction.

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

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

The description is a single, well-organized paragraph that front-loads user intent examples and key behavior. It is not overly verbose; every sentence adds meaning. While it could benefit from bullet points for the source fan-out, it remains efficient and readable. The structure is effective for an AI agent.

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

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

Given the complexity (multiple data sources, fallback logic, window handling, and no output schema), the description comprehensively covers all necessary aspects: what the tool does, its parameters, source behavior, return format, and when to use an alternative. No gaps are apparent, and it fully equips an agent to invoke the tool correctly.

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

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

The input schema already provides 100% description coverage for all 3 parameters. The description adds value by clarifying that 'since' accepts both ISO dates and relative shorthand (with examples like '7d', '30d', '3m', '1y'), and that 'value' can be a ticker or zero-padded CIK. This enriches the schema without redundancy, earning a score above the baseline of 3.

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

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

The description begins with a list of user-intent examples ('What's new with X', 'latest on Y'), precisely stating the tool returns a change feed for a company in a recent window via one parallel call. It explicitly distinguishes from the sibling tool 'entity_profile', which is for static profiles. The verb 'fans out' and the resource 'change feed for a company' are specific and clear.

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

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

The description provides explicit usage guidance: it lists example queries, explains when to use this tool (for recent changes) and when to use the alternative 'entity_profile' (for static profiles regardless of window). It also details the internal sources and fallback behavior, helping the agent decide contextually.

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 (idempotentHint=true, destructiveHint=false), the description adds key behavioral traits: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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 four sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words, efficient and clear.

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 could mention return behavior (e.g., success confirmation), but it adequately covers usage, persistence, and integration with sibling tools. For a simple write operation, it is sufficiently complete.

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

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

Schema coverage is 100% with both parameters described. The description reinforces the key-value pair concept and gives practical examples. It adds value by explaining scope ('scoped by your identifier') and suggesting use cases, going beyond the schema's type definitions.

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

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

The description clearly states the tool saves data for later reuse, providing specific examples like 'resolved ticker, target address, user preference, research subject'. It distinguishes from sibling tools recall and forget by explicitly 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?

The description explicitly advises when to use (when discovering something worth carrying forward) and mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. This provides clear guidance on tool selection.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes beyond these to disclose additional behaviors: every identifier is labeled with the source that established it, unresolvable identifiers are explicitly listed under `unresolved`, enrichment degrades gracefully when external sources are unavailable, and each call cascades through multiple endpoints. This rich context exceeds what annotations alone provide and is not contradictory.

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

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

The description is long but well-structured, opening with example queries, then a core purpose statement, followed by clearly labeled supported types. Every section adds functional value, and the length is justified by the tool's complexity. It could be slightly more concise in the company section, but the density is appropriate for the subject matter.

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 takes on the responsibility of explaining return values, and it does so thoroughly: for company it lists CIK, ticker, company_name, LEI, FIGI, ownership data, and an `unresolved` field; for drug it specifies RxCUI, ingredient, brand, and a citation. It also covers failure modes (unresolved identifiers, external source unavailability) and the internal cascading, making the tool's behavior and outputs clear.

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

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

The input schema already provides full descriptions for both parameters, including enum for type and examples for value. The description compensates by clarifying that company accepts ISIN in addition to ticker/CIK/name, explains the ISIN-to-LEI mapping, and elaborates on how the value input corresponds to resolution outcomes. This adds meaningful nuance beyond the schema, though the schema already covers the basics sufficiently.

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 defines the tool's purpose with a specific verb ('resolve') and a specific resource ('user-spoken NAME to canonical/official identifiers'). It provides concrete example queries and distinguishes itself from sibling tools by stating it supplies the IDs other tools require as input. The function is 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 explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is a clear directive on when to invoke this tool. It lists example command patterns and supported entity types, and notes that it replaces 2-3 manual lookups, giving clear expectations. No exclusions are needed because the examples and directive establish usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it probes multiple entities, uses ai_visibility_check, returns ranked list with score/confidence/signal density, and treats first entity as subject. 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 sentences with a parenthetical, each sentence earning its place. It is front-loaded with purpose, then details the process and use case. No wasted words.

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

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

With 4 parameters, 100% schema coverage, and no output schema, the description adequately explains the return (ranked list with score/confidence/signal density) and special behavior (first entity as subject). Could mention caching or costs, but overall sufficient.

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

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

Schema description coverage is 100%, setting baseline at 3. The description adds meaning by explaining the first entity is 'subject' for narrative and that context disambiguates common names. This goes beyond the schema's 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 compares AI visibility across multiple entities, using specific verb 'compare' and resource 'AI visibility across entities'. It distinguishes from siblings like ai_visibility_check and compare_entities by stating it probes multiple entities and ranks them.

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use this tool over single-entity checks, though it does not explicitly state when not to use or list 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?

Discloses important behaviors: bundlephobia first measurement may take 5-30s, partial failures degrade gracefully with a 'sources_failed' list. Annotations already declare readOnly, openWorld, idempotent; 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 efficient and front-loaded, but slightly dense. Could be split into shorter sentences for easier scanning, but still very effective.

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?

Comprehensively covers input (package name, optional version), behavior (data sources, potential delays, graceful degradation), and output (summary block with specific fields, per-advisory detail, links, alternative versions). No output schema, but return 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% for both parameters (package, version). The description adds context beyond schema: mentions scoped packages are accepted and version defaults to latest. This enriches parameter understanding.

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

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

The description explicitly states the tool's composite purpose: 'should I add this npm package to my project' check, covering license, advisories, version history, and bundle statistics. It clearly distinguishes itself from other tools by being a one-call aggregate.

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

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

Provides explicit when-to-use guidance ('when an agent asks is X safe / popular / small') and when-not-to-use ('NPM ecosystem only; other ecosystems fall under deps.dev:version directly'). This helps the agent choose correctly among siblings.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds rich implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character limit with truncation flagging. 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 a single, well-structured paragraph of about 5 sentences. It front-loads the main purpose and every sentence adds distinct value. No redundancy or fluff.

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

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

Given three parameters and no output schema, the description covers the algorithm, limits, pairing, and return details (offsets, similarity scores). It is fully self-contained for an agent to decide when and how to use 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%, providing baseline of 3. The description adds value beyond schema with examples for query, explains the text cap, and details the embedding method and windowing, which are not in the schema.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record' and specifies the use case: when a record is too large for the prompt. It distinguishes from siblings by explicitly mentioning how it pairs with ask_pipeworx_grounded.

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 advises when to use: 'Use when the record is too big to cram into the prompt.' It also describes the output and pairing with another tool. While it doesn't list exact when-not-to-use scenarios, the context is clear.

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds value by detailing return types ('l' and 't' folders/tables) and path behavior, going beyond structured metadata.

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, each carrying essential information. No redundant phrasing. Front-loaded with purpose followed by usage instructions.

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

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

Given a single parameter, thorough annotations, and no output schema, the description adequately explains input behavior and expected output types. It could elaborate on the exact structure of returned items, but the provided details are sufficient for a browse 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 a clear description. The description adds context by explaining the default value and providing real-world path examples, which enhances the schema's documentation.

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 browses the ASKdata subject tree, specifies default path behavior, and demonstrates drill-down capability. It distinguishes itself from sibling tools by its focus on hierarchical subject navigation.

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

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

Provides clear usage examples (default and deeper paths) but does not explicitly mention when to avoid this tool or suggest alternatives. It gives enough context for appropriate use.

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

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

The description discloses key behaviors beyond annotations: returns new subscription id, requires OAuth, documents delivery constraints (SMS cap, webhook auto-disable, phone verification), and notes that webhook secret is returned once. 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 substantive paragraph that front-loads the purpose. It covers all necessary aspects without redundancy, though it could benefit from bullet points for the type-specific parameters to improve readability.

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

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

Given the tool's complexity (nested objects, multiple types, delivery options) and absence of an output schema, the description covers the return value, side effects, constraints, and even webhook verification steps. It is highly comprehensive.

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 significant meaning: explains each subscription type with concrete examples, details delivery channel formats and constraints (phone must be verified, SMS cap, webhook signing secret). This enriches the schema's properties.

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 'Create a proactive monitoring subscription to a live-data event stream', specifying the verb and resource. It enumerates supported subscription types and delivery channels, and the name 'subscribe' differentiates it from sibling tools like 'list_subscriptions' or 'unsubscribe'.

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

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

The description provides context on when to use each subscription type (e.g., 'sec_8k' for 8-K filings) and prerequisites (Pipeworx OAuth account). It implicitly sets expectations but does not explicitly contrast with alternatives like 'unsubscribe' or 'list_subscriptions'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds detail that it returns example questions with exact tool+argument shapes from the live catalog, which is useful 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 relatively long but well-structured: starts with common user phrasings, then defines purpose, output, and usage options. Every sentence adds value for the agent, though it could be slightly more concise.

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

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

Given the tool's role as an onboarding entry point, the description fully covers when to use it, what it returns (category-bucketed examples with tool/argument details), and how to focus it. No output schema is needed as the description explains the output nature.

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 parameter. The description explains the topic parameter's possible values (finance, pharma, etc.) and the behavior when omitted (full cross-category spread), adding meaning beyond the schema.

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

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

The description clearly states it is the onboarding entry point for a new agent, returns category-bucketed example questions, and can be focused by topic. It distinguishes itself from siblings by instructing to use this tool first when unsure what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternative phrasings for what users might type. It also explains the effect of the optional topic parameter and omitting it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns dimensions and value lists, providing output context beyond annotations. 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?

Two concise sentences: the first states the core function, the second specifies path format and output purpose. No unnecessary words.

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

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

Given a single parameter and no output schema, the description sufficiently explains what the tool does, what it returns, and how to use the parameter. It is complete for the agent to understand and 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 high (100%), but the schema description only gives an example. The tool description adds the crucial constraint that the path must end in '.px' and be the full path, which the schema lacks, thus adding meaning.

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

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

The description clearly states the tool fetches dimension definitions and valid coded values for a specific type of table (Kosovo ASKdata PxWeb), using a specific verb and resource. It distinguishes itself from sibling tool 'query_table' by focusing on metadata retrieval.

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

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

The description provides explicit guidance on when to use the tool: before building a query_table body, as it returns required data. It also specifies path format requirements, helping the agent avoid errors.

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

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

Annotations already indicate idempotent and non-destructive. Description adds ownership enforcement and deactivation semantics, providing value 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 concise sentences with no wasted words. The action and key constraints 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 single-parameter tool with no output schema, the description covers purpose, ownership, side effects (deactivation), and data retention, making it complete.

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

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

Schema coverage is 100% and parameter 'id' is described in schema. Description does not add further meaning beyond the schema, meeting baseline.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

Ownership enforcement ('you can only cancel your own subscriptions') and behavioral outcome (deactivation vs deletion) are explained. Missing explicit when-not-to-use, but context is sufficient.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description adds highly important behavioral detail: the meaning and non-evidentiary nature of 'could_not_verify' (with an explicit warning not to treat it as evidence), the 'unsupported' outcome, the return of a verdict with citation, and the automatic routing to structured vs. grounded pipelines. It also warns about a specific failure mode (verification_error), which is exactly the kind of context an agent needs.

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

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

The description is somewhat long, but it is well-structured: trigger phrases first, then purpose, usage, routing, return values, critical caveats, and finally the efficiency gain. Each sentence adds value, and the 'IMPORTANT for callers' section is necessary. It could be slightly more concise (e.g., trimming the seven trigger phrases), but it remains focused 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?

There is no output schema, so the description carries the full burden of explaining what the tool returns. It lists all verdict types, the citation mechanism, the 'could_not_verify' error structure, and the 'unsupported' meaning. Combined with the rich annotations, this gives an agent everything needed to interpret results correctly, including edge cases. The description is exceptionally complete for the tool's complexity.

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

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

The schema already describes both parameters ('claim' and 'tolerance_pct') with 100% coverage, which sets a baseline of 3. The description adds meaningful context beyond the schema by mentioning 'exact percent-delta math', the default tolerance cap of 5, and the use of tolerance for hallucination detection (set 1–2). This enriches an agent's understanding of how to set the parameters.

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

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

The description opens with multiple natural-language trigger phrases ('fact check', 'verify the claim', 'confirm or refute') and immediately states the core function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by specifying the two internal pathways (structured SEC EDGAR for company-financial claims, grounded pipeline for all else) and notes it replaces several sequential steps. This is a specific verb+resource+scope with strong differentiation.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also explains the two routing branches based on claim type. However, it does not explicitly name sibling tools as alternatives or state when NOT to use this tool (e.g., when the user just wants general information rather than a verdict), leaving some ambiguity against tools like ask_pipeworx_grounded or deep_research.

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