Makstat Mk

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 value by detailing the output format (per-model {score, confidence, signals, raw_response} + combined view) and clarifying billing implications for the Anthropic probe. No contradictions with annotations.

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

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

The description is concise (three sentences) and well-structured. It front-loads the core action, lists key parameters, and provides output summary. Every sentence adds value without redundancy.

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

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

Given no output schema and rich annotations, the description covers the essential behavior: probing LLMs, scoring, return structure, and key usage condition (apiKey). It omits error handling or rate limits, but for a non-destructive read tool with good annotations, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond the schema: it explains the default model, that _apiKey is only needed if 'anthropic' is in models, and that 'context' helps disambiguate. This additional clarity justifies a 4.

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

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

The description clearly states it probes LLMs for brand visibility and scores them. It specifies the verb 'Probe' and resource 'business/brand/product/topic'. However, it does not explicitly distinguish from sibling tools like 'scan_competitor_ai_presence', which seems similar.

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

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

The description explains it's useful for AI-marketing audits, pre-launch checks, and competitive monitoring. It also notes when to use the _apiKey parameter (only if probing Anthropic). But it does not provide explicit when-not-to-use guidance or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description's additional behavioral context is a bonus: it discloses that the tool routes requests to a curated network of thousands of sources, fills arguments automatically, returns citations, and is fast ('one fast call'). These behaviors go beyond the structured annotation hints and give the agent a clear mental model of what will happen when invoked. 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 on the longer side but front-loads the critical directive ('PREFER OVER WEB SEARCH'), then packs in domains, trigger phrases, examples, and routing guidance. Every sentence adds practical value, though there is some redundancy (e.g., repeating that web search could also answer it). The ALL CAPS keywords and clear 'START HERE' / 'Step up only when needed' structure make it scannable. It earns a 4 for density and structure despite minor repetition.

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

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

For a complex router tool with no output schema, the description covers the essential contextual elements: what it returns (structured answer with pipeworx:// citation URIs), when to use it, when not to, which siblings to consider, and its operational characteristics (works on every tier, one fast call, covers news). It also provides enough examples to disambiguate the question style. The description is complete for an agent to select and invoke the tool correctly in most scenarios.

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

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

Schema coverage is 100%, with all parameters documented as aliases for the natural-language 'question' parameter. The description adds value beyond the schema by specifying what kinds of questions to submit (trigger phrases, domains, real-world entities/events/numbers) and giving six concrete examples. This enriches the parameter semantics beyond the schema's generic 'Your question or request in natural language.' A 4 is justified because the schema already fully documents parameter names, and the description supplements, not replaces, that 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 uses a specific verb+resource: 'Routes the question to the right one of 5,908 tools across 1540 verified sources... returns the structured answer with stable pipeworx:// citation URIs.' It clearly identifies the tool as a question-answering router for authoritative structured data and distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research. The scope is unambiguous and memorable.

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 is explicit about when to prefer this tool over web search, listing domains (SEC filings, FDA, FRED/BLS, patents, real estate, weather, etc.), trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and concrete examples. It also explicitly states when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research' and clarifies that news is handled by this tool. No guidance is left to inference.

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

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

Excellent disclosure beyond the annotations: it reveals the tool is a live experimental surface whose routing can change dynamically whenever a candidate is under test, discloses the current inactive state with a specific retirement date, confirms current parity with stable, and guarantees full functionality ('Falls back to nothing — this IS a full working router'). The readOnlyHint, openWorldHint, and idempotentHint annotations are consistent with a question-routing tool, and the description complements rather than repeats them.

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

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

Four dense sentences, each carrying distinct information: identity and scope, current experimental state, usage instruction, and the no-fallback guarantee. Slightly long due to the precise retirement date, but that detail substantiates the 'currently matches ask_pipeworx exactly' claim. Core identity is front-loaded ahead of the operational 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?

For a dynamically experimental router, the description covers the operational essentials: what it is, scope of 5,908 tools, when behavior changes (candidate under test), current parity with stable, invocation approach, and how output is used. The implicit pointer to ask_pipeworx for response shape is a reasonable substitute for a missing output schema. Minor gap: it never specifies what kinds of candidate routing improvements might appear while under test.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the single required 'question' field. The description adds only that the tool takes the 'same arguments' as ask_pipeworx, which orients the agent but does not deepen parameter understanding. Baseline 3 is appropriate because the schema already carries the semantic weight.

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 identifies the tool as a universal router that answers questions by dispatching across the same 5,908 tools as ask_pipeworx, and frames it explicitly as the experimental beta edge of that sibling. It distinguishes itself from the stable ask_pipeworx, though it leans on that sibling for the core functional definition ('identical universal router... same response shape') rather than fully stating the purpose independently.

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?

Gives explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains the beta context (results compared against the stable router to decide merges). It stops short of explicit when-not-to-use exclusions, such as preferring stable ask_pipeworx for consistency or ask_pipeworx_grounded for grounded answers, leaving those to inference from 'experimental edge.'

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds materially more: it extracts answers only from tool results, returns verbatim evidence, can explicitly refuse with categorized refusal_reason values, and reveals the extra LLM call cost. There is no contradiction with 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 front-loaded with the core purpose and grows into behavioral detail, output shape, usage rationale, and cost comparison. Every sentence earns its place, and the structure makes the tool's unique value immediately visible.

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

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

For a complex routing tool with no output schema, the description thoroughly explains success and refusal return shapes, evidence behavior, applicable domains, and the relationship to ask_pipeworx. An agent has enough information to decide when to invoke it and what to expect back.

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

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

Schema description coverage is 100%, with the sole required parameter 'question' fully documented along with its aliases. The description adds no new parameter-level semantics, but given the schema already handles this completely, the baseline score of 3 is appropriate.

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

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

The description opens with a specific and distinctive purpose: a hallucination-resistant answer mode for high-stakes reads. It clearly differentiates itself from the sibling ask_pipeworx by describing its evidence-grounded extraction and explicit refusal behavior, so an agent can distinguish it without inspecting schemas.

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

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

It gives explicit when-to-use guidance: use when answers will be quoted, cited, or acted on, especially for financial, legal, medical, or public-statement facts. It also names the alternative ask_pipeworx and the condition favoring it ('casual lookups'), plus the cost tradeoff of one extra LLM call.

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 read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral detail: market resolution, classifier fan-out, response shapes, safety short-circuits, wide-spread warnings, resolution-rule risk. No contradictions. Fully transparent.

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

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

The description is long but well-structured with front-loaded purpose, examples, and detailed sections. Every part adds value. Could be slightly more concise, but not overly verbose given complexity.

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

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

Given no output schema, the description thoroughly explains return shapes, resolver contract, parent event extractor, news fields, safety, wide spread, and resolution-rule risk. It covers all necessary context for an agent 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% with good parameter descriptions. The description adds minimal extra semantics beyond the schema (e.g., examples for market, clarification of depth options). Baseline 3 is appropriate; description does not significantly enhance understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It provides specific verb 'Research' and resource 'Polymarket bet', and distinguishes from siblings by its unique multi-source fan-out and classifier system. Use cases like 'should I bet on X' are explicit.

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'', etc., giving clear context. It does not explicitly exclude other uses or compare to siblings, but the classifiers and examples imply when to use. No misleading 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 a single paragraph but well-structured with example queries upfront, followed by specific details per entity type. Every sentence adds value, there is no redundancy, and it is appropriately concise for the complexity.

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

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

Given the complexity (two entity types, different data sources) and lack of output schema, the description covers all essential aspects: data sources, sorting, citations, and efficiency gains. It is sufficiently complete for an AI agent to understand what the tool returns and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds substantial meaning beyond the schema: it explains that 'type=company' pulls financial metrics and 'type=drug' pulls adverse event data, and that 'values' are tickers/CIKs or drug names. It also reiterates constraints like 2-5 items.

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

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

The description uses specific verbs like 'compare' and 'side-by-side comparison' and clearly identifies the resources: companies or drugs. It distinguishes itself from sibling tools like entity_profile and sequential lookups, fulfilling the criteria for a high score.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also lists example queries and describes what data is pulled per entity type, effectively excluding 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?

The description goes far beyond the annotations: it discloses the decomposition behavior, parallel tool routing, gaps[] semantics with a 'never invented' guarantee, contradictions[], citation_uri fetchability conditions, semantic excerpting instead of head-truncation, and expected latency. This is rich behavioral context that the readOnly/openWorld/idempotent annotations do not convey.

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 information-dense; every clause conveys a meaningful distinction or behavior. It front-loads the critical auth constraint and sibling routing, then moves through scope, output packet, depth semantics, and latency. It is structured enough that no sentence feels wasted, though some repetition exists around the structured-vs-open-web distinction.

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 the absence of an output schema, the description fully covers return packet shape, citation semantics, gaps/contradictions behavior, auth requirements, tier differences, timing expectations, and sibling alternatives. An agent has everything needed to select and correctly invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning beyond the schema by explaining 'thorough' requires a paid plan, clarifying that 'standard' re-angles unanswered gaps, and detailing how each depth tier affects iteration and contradiction scanning. It reinforces and expands on the enum values, so it earns a 4.

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

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

The description states a specific action and resource: 'Grounded multi-source research across Pipeworx's 1540 STRUCTURED data sources... in ONE call.' It also clearly distinguishes itself from open-web search and from the ask_pipeworx sibling by explaining what it is NOT ('this is NOT open-web search') and what it is best for (broad/multi-part structured-data questions).

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

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

Usage guidance is explicit and actionable: use deep_research for broad multi-part structured questions, use ask_pipeworx for single lookups or trending/news topics, and use ask_pipeworx if not signed in. It also describes when depth tiers apply and how 'standard' vs 'thorough' behave in follow-up hops.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by explaining it returns top-N results with full schemas ready to call, but does not mention rate limits or potential performance issues. 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 moderately long but front-loaded with the core purpose. The list of domains is extensive but useful. Every sentence adds value, though some could be 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 no output schema, the description explains what the tool returns (names, descriptions, full schemas with examples). It covers the key aspects for an agent to decide to call it, though more detail on return structure would help.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add new meaning beyond mentioning 'top-N' which refers to limit. 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 finds tools by describing data or task, listing many example domains. It explains it returns top-N relevant tools with full schemas, distinguishing it from sibling tools that are domain-specific.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context on when to use it, and implies it's for browsing/discovery rather than direct answers.

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

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

Even with readOnly/openWorld/idempotent annotations present, the description adds substantial behavioral context: parallel fan-out behavior, sources_used/sources_failed semantics, empty sections meaning real absence of data, and private companies resolving to resolved:false with a notes line rather than a hard failure. These details are not inferable from the annotations alone.

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

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

The description is long but front-loaded with user-intent examples and the core purpose, and nearly every sentence adds functional detail about sources, outputs, or resolution behavior. It is denser and more sprawling than ideal, but the length is largely justified given the tool's complexity.

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

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

With no output schema, the description compensates by documenting the key return fields, source coverage, failure semantics, input resolution, and the private-company edge case. An agent has enough information to select the tool, invoke it correctly, and interpret the response appropriately.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that names resolve through SEC EDGAR, that a name-valued input produces resolved_from/resolved_to, and that private companies yield resolved:false. This adds meaningful invocation semantics rather than merely restating the schema.

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

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

The description clearly identifies a specific verb-resource purpose: producing a full cross-source profile of a US public company in one parallel call. It supports this with concrete user-phrase examples and differentiates the tool from chaining single-pack SEC/XBRL/news lookups.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups when the user asks for a holistic company view. It also explains accepted input types and private-company behavior, though it does not explicitly name sibling tools or describe when not to use it.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, but no contradiction. Additional behavioral context is provided beyond annotations.

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

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

Two sentences, front-loaded with core action, no fluff. 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?

With one parameter, destructive hint provided, and no output schema, the description covers all needed context for an AI agent 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% for the single 'key' parameter. Description only repeats the schema description 'Memory key to delete' without adding new meaning beyond what the schema already provides. Baseline score applies.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes it from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and suggests 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and clarifies the output is a single text blob for site-root/llms.txt. No contradictions.

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

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

The description is concise (two paragraphs) and front-loaded with the main action. Every sentence adds value: first paragraph defines the tool and output, second lists use cases. No fluff or repetition.

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

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

With only 2 parameters, no output schema, and rich annotations, the description fully covers what the tool does, its inputs, output format, and use cases. 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 clear descriptions for both parameters (url and max_links). The description adds minimal extra meaning (e.g., example URL format) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using specific verbs ('generate', 'fetches', 'extracts', 'emits') and specifies the resource ('llms.txt file'). It distinguishes itself from siblings 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?

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing a competitor) and context. However, it does not explicitly state when not to use the tool or compare it to alternatives, but the sibling list implies differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds transparency by listing the exact fields returned (id, type, params, etc.) and default behavior (active only). No contradiction. Could mention pagination or rate limits, but not necessary for this simple tool.

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

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

Extremely concise: two sentences. First sentence states core function and return values. Second sentence provides usage guidance. Every sentence earns its place; no fluff.

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

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

Despite no output schema, the description explicitly lists what is returned. Together with annotations and schema, it fully covers the tool's behavior, parameters, and usage context. No gaps.

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

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

Schema coverage is 100% and the only parameter 'include_inactive' is fully described in the input schema. The description does not add any additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Clearly states the action ('list') and resource ('subscriptions'), and scopes to 'the caller's active subscriptions'. Distinguishes from sibling tools like subscribe and unsubscribe by implying listing for review before adding or finding id to cancel.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies not to use when intending to add or cancel directly, guiding the agent to the correct sibling tools.

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

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

Even though annotations provide no hints (all false), the description adds substantial behavioral context: it explains the claim_token flow (filing returns a token, which can be reused to read status), rate limiting (5/day), cost (free, not quota), and privacy guidance ('don't paste the end-user's prompt'). This goes well beyond annotation signals 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 information-dense; every sentence contributes: purpose, usage triggers, exclusions, claim-token behavior, rate limit, and cost. It is front-loaded with the core action. Minor redundancy exists (e.g., 'Pipeworx tool names are the ones this connection lists' could be tighter), but nothing is wasted.

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

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

For a tool with no output schema, the description covers key workflows: filing feedback, retrieving status via claim_token, and rate limits. It does not describe the exact response structure beyond the token, but the provided information is sufficient for a typical agent to use the tool correctly. A 4 reflects the absence of an explicit output schema description while acknowledging the token explanation.

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

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

Schema coverage is 100%, so the schema already documents all four parameters well. The description adds value by explaining the claim_token lifecycle ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'), which gives extra semantic context not fully captured in the schema. The example invocation also clarifies usage, so a 4 is warranted.

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

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

The description opens with a specific action and target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like ask_pipeworx, focusing on feedback rather than inquiry. The enumerated feedback types (bug, feature/data_gap, praise) further clarify scope.

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

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

Provides explicit when-to-use scenarios: '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).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' and a disambiguation note about Pipeworx tool names. This surpasses basic guidance by naming the alternative action.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds caching window (5min-1h), data source (CF analytics-engine), and no PII. 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?

Three sentences plus bullet points, front-loaded with output. 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 one optional parameter, no output schema but return values are described (top tools, packs, volume). Caching and behavior fully explained. Complete for a simple trending tool.

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

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

Schema describes window enum with coverage 100%. Description adds context that shorter windows show 'hot right now' and longer show 'steady-state demand', adding value beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume. Uses specific verbs and distinguishes from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Lists three explicit use cases (discovering hot sources, confirming canonical tools, aligning use cases). Does not explicitly name alternatives or state when not to use, but 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, which are consistent with a scanning tool. The description adds extensive behavioral context: monotonicity violation checks, partition-sum logic, semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live CLOB depth, and what to do if realizable_edge_pp ≤ 0. This goes well 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 well-structured with clear sections for modes, semantic anchor, partition filter, response, and fill check. It is front-loaded with the core purpose and usage modes. However, it is somewhat lengthy (approx. 250 words) and could be slightly more concise without losing key 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 (two modes, internal checks, fill validation), the description covers most essential aspects. It describes the response fields (opportunities[], partition_check) and behavior for each mode. However, it lacks details on error handling (e.g., invalid event slug) and does not specify exact field types in the response. The absence of an output schema is partially compensated.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains that 'event' triggers single-event mode walking child markets and performing axis ordering and partition checks, while 'topic' triggers cross-event scanning with Jaccard similarity filtering. It also describes the response structure for each mode and the fill check behavior.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities), and mechanism. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection through specific mathematical checks.

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

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

The description explicitly provides usage guidelines: 'Call with NO args for a trending_scan... pass event for... pass topic for...' It explains when to use each mode, recommends event mode for specific markets, and contrasts cross-event mode's ability to catch patterns missed by single-event mode. It also advises against trading when fill check shows zero realizable edge and points to polymarket_fill_risk for custom sizing.

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

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

Annotations indicate safe read-only, idempotent behavior. The description adds extensive details: caching policy, segment computation, edge calculation, knobs, diagnostics, and exclusion of Fed bets. 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 comprehensive but verbose, with heavy technical detail that could be streamlined. It front-loads the purpose but includes model specifics that may be excessive for many agents.

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

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

Without an output schema, the description fully details the response structure (by_segment, fed_candidates, diagnostics) and explains key fields like edge_pp_net and kelly_fraction, 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%, so baseline is 3. The description adds context by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining their role in filtering, which goes beyond individual 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on discrepancy detection rather than cross-platform arbitrage.

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

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

The description provides context for use (daily bet discovery) and explains the three segments and their applicability. However, it does not explicitly state when not to use or mention alternatives for other tasks.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds detailed behavioral context: response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day), and data source caveats (daily closes, cache-miss triggers).

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: purpose first, then response fields with clear labels, then limitations. However, it is somewhat verbose; a few sentences could be tightened without losing meaning.

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 the response structure (tracked, expired, snapshot_dates) with field details. It also covers limitations and data source behavior, making it self-sufficient for an agent to understand what to expect.

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 descriptions cover 100% of parameters. The description adds default values (14 days, '1wk'), clamp for days (max 30), and explicitly lists window families (24hr, 1wk, 1mo) which are not enumerated in the schema. This adds significant semantic value.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It contrasts fresh vs. old edges, distinguishing it from the sibling tool 'polymarket_edges'.

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

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

The description explicitly tells when to use the tool (to assess edge persistence and decay) and provides limitations (60-day TTL, daily closes). It implies not for intraday analysis, but doesn't explicitly state when not to use vs. 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?

In addition to annotations (readOnlyHint, etc.), the description details internal behavior: walks the order book, computes VWAP, slippage, verdict. For basket mode, explains theoretical vs realizable sums, capture ratio, and risks like forced directional position and partial fill threats.

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

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

Well-structured with clear sections (SINGLE-MARKET, BASKET) and bold labels, but slightly verbose. Every sentence adds value, but could be trimmed further 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?

No output schema, but the description enumerates all returned fields for both modes, including edge cases like thin_legs, forced_directional_risk, and max_clean_notional_usd. Covers what the tool does not do (capture overround on thin books).

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

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

Schema coverage is 100%, but the description adds context: e.g., for `size_usd` explains interpretation differs between single-market (spend/proceeds) and basket (settlement notional). Provides default and clamp values beyond schema.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like 'polymarket_arbitrage' by advising to use this before acting on arb signals.

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

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

Explicitly says 'REQUIRES one of `market` or `event`' and describes when each mode applies. Provides concrete advice: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing gross vs net spreads, fee treatment, compatibility warnings, unclassified-leg exclusion, temporal alignment null semantics, and the fact that pairings are keyword-matched rather than source-verified. This gives an agent an exceptionally clear behavioral model.

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 very dense, sprawling block of text that covers many important behaviors but is far from concise. It front-loads the core purpose but then stacks safety fields, warning codes, and counter explanations with minimal structure, making it harder to scan than it should be.

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 must carry the full burden of explaining the response shape, and it does: raw leg prices, top_spreads_pp, compatibility fields, per-entry flags, skipped counters, fees_note, and temporal alignment semantics. This is remarkably complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between the topic mode and the explicit override parameters, confirming both modes use the same matching logic, and giving concrete examples of ticker/slug formats.

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

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

The description opens with a specific statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from sibling tools by naming both venues and explaining the two input modes.

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

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

The description explains when to use topic shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics are not automatically tradeable. It does not explicitly name sibling alternatives, but it provides clear mode-selection and caveat guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the behavioral trait of a cell-count limit and clarifies that the POST request is effectively a query, providing context beyond annotations.

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

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

The description is two sentences, front-loaded with purpose, and each sentence provides essential information without redundancy.

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

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

The description covers the body format and key constraint (cell-count limit). It lacks details about the response structure beyond format, but the output format is stated. For a tool with no output schema, this is adequate.

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

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

Schema coverage is 100% and the description does not add additional meaning to the parameters beyond what the schema already specifies. The description restates the body format but does not explain individual fields.

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'), the resource ('MakStat table'), and the output format ('json-stat2'). It distinguishes from sibling tools like table_meta, which likely provides metadata.

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

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

The description provides explicit guidance on narrowing dimension values using codes from table_meta and warns about the cell-count limit. It implies a prerequisite but does not explicitly state when to use or avoid this tool.

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

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

Annotations already show readOnlyHint, idempotentHint, destructiveHint. Description adds scope (scoped to identifier) and listing behavior, enhancing 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?

Concise 4-5 sentence description with front-loaded purpose, no fluff. 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?

Covers core behavior, usage, and scoping. Return format not specified but no output schema exists; overall complete for a simple retrieval tool.

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

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

Schema covers the key parameter with description 'omit to list all keys'. Description reinforces this and provides concrete usage examples, adding value beyond schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys. It gives concrete examples (ticker, address, notes) and distinguishes from sibling tools 'remember' and 'forget'.

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

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

Provides clear context for when to use (look up stored context) and mentions alternatives (remember, forget). Lacks explicit 'when not to use' but still strong guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds value by detailing return fields (source, citation_uri, raw payload), the effect of mark_read (only newer events on next call), and that polling is acceptable. Does not cover pagination or rate limits, but still informative.

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

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

Well-structured with clear hierarchy: purpose, return details, filter options, behavior note, and alternative access. Every sentence adds value; no fluff. Slightly longer than strictly necessary, but still concise.

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

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

Given no output schema, description adequately explains return fields (source, citation_uri, payload) and behaviors (mark_read, polling). All 5 parameters are addressed in schema and description. Missing edge cases like what happens with limit exceeded, but overall sufficient for an agent.

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

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

Schema provides descriptions for all 5 parameters (100% coverage). Description reinforces with examples ('sec_8k' for type, ISO format for since) and explains the mark_read behavior, adding substantial 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?

Clearly states 'Pull fired events from your subscription feed' with specific verb and resource. Mentions alternative access via GET endpoint, but doesn't explicitly differentiate from sibling tools like list_subscriptions, so not a perfect 5.

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 context that polling works fine and mentions alternative script access, but lacks explicit when-to-use vs other tools (e.g., when to choose this over list_subscriptions). No exclusions or alternatives to sibling tools given.

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

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

Annotations already declare safety (readOnlyHint, idempotentHint, destructiveHint false). Description adds valuable behavioral context: fans out to multiple sources, fallback logic, soft-fail for USPTO, and output format (structured changes[] with citations). No contradiction.

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

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

Description is packed with information but end-to-end efficient. Front-loads examples. Every sentence adds value. Could be slightly more structured (e.g., bullet points), but remains concise overall.

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 moderately complex tool (multiple sources, fallback, date parsing), the description is complete. Covers behavior, input formats, fallback logic, output structure, and sibling differentiation. No output schema, but description adequately describes return format.

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

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

Schema coverage is 100%, but description adds semantics: explains `since` accepts ISO or relative shorthand with examples, suggests '30d' or '1m' for typical monitoring, and clarifies `value` can be ticker or zero-padded CIK.

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

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

Description clearly states the tool retrieves a change feed (SEC filings, news, patents) for a company in a recent time window, using specific verbs like 'fans out'. It explicitly distinguishes from sibling tool entity_profile (static profile vs. dynamic changes).

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

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

Provides explicit guidance: when to use (e.g., 'What's new with X') and when not to ('Use entity_profile instead when you want the static profile...'). Also details fallback behavior (GDELT→GNews) and acceptable date formats.

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 behavioral traits beyond annotations: scoping by identifier, persistence differences for authenticated vs. anonymous users (24-hour retention). Annotations provide idempotentHint=true and destructiveHint=false, which are consistent and complemented by this 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?

Well-structured and concise: front-loaded with purpose, then usage, behavior, and pairing. Every sentence adds value without redundancy.

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

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

Given the simple two-parameter tool with full schema and no output schema, the description covers purpose, usage, behavior (persistence, scoping), and pairing with siblings, making it fully complete for agent understanding.

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

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

Schema coverage is 100% with adequate descriptions for key and value. Description adds context about storing key-value pairs and gives examples in usage guidelines, elevating semantics beyond mere schema definitions. Not a 5 because no additional parameter-specific details beyond examples.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, specifying the verb 'save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by explicitly mentioning 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. Also indicates when to use alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: the tool cascades through multiple endpoints, degrades gracefully when GLEIF or OpenFIGI is unavailable, labels identifier sources, explicitly reports unresolved identifiers, and returns candidates rather than guessing on ambiguous matches. No contradiction with annotations.

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

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

The description is front-loaded with user-intent examples and a direct usage trigger, and most sentences carry useful information. However, the company type section is a sprawling single paragraph with heavy parentheticals, and some details are repeated; bulleted structure would improve readability without losing 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?

With no output schema, the description carries the burden of explaining return behavior, and it does thoroughly: identifiers are source-labelled, unresolved identifiers are explicitly listed, ambiguous bonds return figi_candidates, and drug results include an RxNorm citation link. It gives an agent enough to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema. For value, it warns to pass only the entity name and explains the bond-issuer pitfall: 'trailing security-class words match nothing.' For type, it defines what each resolved identifier set includes and which sources provide 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 states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It opens with concrete query patterns and enumerates supported entity types, making it easy to distinguish from sibling tools like entity_profile or compare_entities.

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

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

It gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also clarifies behavior when a name matches multiple instruments, returning figi_candidates rather than asserting a single result. It does not explicitly name sibling tools to avoid or alternatives to prefer, slightly weakening the when-not 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 indicate read-only, idempotent, non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density per entity. No contradictions.

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

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

Four sentences, each contributing unique information. Front-loaded with primary action. No fluff.

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

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

Given the 4 parameters and rich annotations, the description adequately explains functionality and output. Missing some detail on score interpretation but sufficient for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema; it merely restates the entities array purpose. No extra 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes. It distinguishes from sibling tool ai_visibility_check which checks a single 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 mentions competitive AI-marketing audits and implies usage when comparing multiple brands. It does not provide explicit when-not or alternative tools, but the context is clear given the sibling list.

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 behavior beyond annotations: fans out across deps.dev and bundlephobia, explains partial failures (bundlephobia first measurement can take 5-30s, sources_failed will list timeouts), and describes return fields in detail. No contradiction with annotations.

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

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

The description is comprehensive and front-loaded with the main purpose. While slightly long, every sentence adds value, covering usage, scope, output, and edge cases. 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 details the return structure: summary block fields, per-advisory detail, links, alternative versions, and error handling. Complete for a composite check tool.

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

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

Schema coverage is 100%, and the description adds context: scoped packages are accepted, version defaults to latest. This provides meaningful extra information without being verbose.

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

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

The description explicitly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by specifying the NPM ecosystem scope and noting that other ecosystems use deps.dev directly.

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?

Gives clear guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also advises that for PyPI/Maven/Cargo/Go, users should use deps.dev:version directly, providing explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Concise, front-loaded with purpose, every sentence adds value. No wasted words. Structure is clear and easy to parse.

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

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

Despite no output schema, description explains what is returned (top-N passages with offsets and scores). Also covers embedding model, windowing, character limit. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds example queries for the 'query' parameter and explains truncation for 'text', but most parameter semantics are already 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?

Description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article). Distinguishes from sibling ask_pipeworx_grounded by noting it is used when the record is too large and pairs with that tool.

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: use when record is too big to fit in prompt, saves context. Mentions pairing with ask_pipeworx_grounded as alternative, but does not explicitly state when not to use. Still, usage context is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by explaining the response structure (folder/table list) and path behavior, which are not evident from annotations alone. 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 concise with two sentences, each serving a purpose: explaining the tool's scope and providing usage instructions. 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 that there is no output schema, the description adequately explains the return format (folder/table list with types). The tool is simple, and the description covers navigation and expected output for a browsing 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% description coverage for the single 'path' parameter, and the description repeats the same information. While examples are helpful, the parameter semantics are fully defined by the schema, so the description adds minimal new 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's purpose: to browse the MakStat subject tree. It specifies the verb 'browse' and the resource 'subject tree' and distinguishes this tool from others by detailing the hierarchical structure (folders vs tables) and 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?

The description provides clear usage guidance: empty path for root, sub-paths to drill down. It explains the returned data types ('l' for folders, 't' for tables) and how to reach tables. It does not explicitly state when not to use or list alternatives, but the context is sufficient.

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

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

The description adds significant behavioral context beyond annotations, including OAuth requirement, supported types with parameter examples, delivery channel specifics (SMS cap, webhook signing secret, auto-disable), and the fact that it returns a subscription ID.

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 purpose first, then requirements, types, and delivery, but it is somewhat verbose. However, every sentence adds value, and the structure aids readability.

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

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

The description covers prerequisites, all supported types with parameters, delivery options with constraints, return value, and edge cases (webhook auto-disable). It is highly complete given the absence of 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?

Despite 100% schema coverage, the description provides detailed explanations and examples for each parameter, such as type-specific formats and delivery constraints, adding substantial meaning beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID, distinguishing itself from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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 mentions the requirement for a Pipeworx OAuth account and provides examples of when to use the tool for different subscription types and delivery channels. It does not explicitly state when not to use it, but the context with sibling tools offers implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds useful behavioral context: it returns example questions drawn from a live catalog, and it's an onboarding tool. No contradictions with annotations.

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

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

The description is relatively long but well-structured. It starts with natural language triggers, then explains output and usage in separate sentences. Every sentence adds value, though it could be slightly more concise.

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

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

For a simple tool with no output schema and one optional parameter, the description is complete. It explains the output format, usage scenarios, and source of examples. It covers all necessary context for an AI 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 description coverage is 100% for the single optional parameter. The description adds value by listing possible topic values (finance, pharma, etc.) and explaining that omitting topic gives a cross-category spread. This goes beyond the schema's description.

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

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

The description clearly states this is the onboarding entry point for an agent to ask about Pipeworx's capabilities. It lists multiple natural language triggers and explains it returns category-bucketed example questions with tool call shapes. It distinguishes from sibling tools like ask_pipeworx and entity_profile by positioning it as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on when to pass a topic vs. omit it. Does not explicitly list alternatives, but the context makes it clear that this is for exploration before using specific tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific output details (dimensions with codes and value lists) and path constraints, enhancing 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 sentences, front-loaded with purpose, 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 single parameter, full schema coverage, strong annotations, and no output schema, description fully covers what the agent needs: input format, output content, and how to use it with sibling 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%, but description adds crucial meaning: clarifies path format (must end in '.px') and provides an example, which schema's brief description lacks.

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

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

Clearly states verb ('Fetch') and resource ('dimension definitions and valid coded values for a MakStat PxWeb table'). Specifies path requirement and relationship to sibling 'query_table', distinguishing it effectively.

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

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

Explicitly mentions that output is used to build selection body for 'query_table', providing clear context. Lacks explicit 'when-not-to-use' but implied by purpose.

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 (which are minimal), the description discloses key behavioral traits: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This adds value and does not contradict annotations.

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

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

Two concise sentences, front-loaded with the core purpose, no extraneous information. Every sentence earns its place.

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

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

Given one required parameter and no output schema, the description adequately covers purpose, ownership enforcement, side effects, and reference to historical data. It is complete for this tool.

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

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

Schema coverage is 100% and parameter 'id' is described. The description adds ownership context but does not enhance parameter semantics beyond what the schema provides.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the action and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by using the verb 'cancel' and referencing subscription ID.

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

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

It explicitly says 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear when-to-use guidance. It does not explicitly name alternatives, but the context of siblings implies when not to use it (e.g., for others' 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enriches these by detailing the two pipeline paths (SEC structured vs grounded), enumerating the exact verdict categories, and clearly distinguishing 'could_not_verify' (which does not count as evidence) from 'unsupported'. It also explains the inclusion of citations and reasoning, going far beyond annotations.

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

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

The description is relatively long, but every section serves a purpose—invocation examples, scope, routing, output, and error semantics. It's front-loaded with natural-language patterns and well-structured, but the density of information makes it slightly less concise than ideal.

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 appropriately explains return values (verdict, actual value, citation, reasoning) and edge cases like could_not_verify and unsupported. It covers the main use cases and the distinction between financial and generic claims. Minor gaps exist (e.g., exact response format, how to present the result to users), but overall it's quite 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 already fully describes both parameters (100% coverage). The description adds meaningful context for tolerance_pct with specific guidance (e.g., 'set 1–2 for hallucination detection') and explains how the default is derived from claim wording. This goes beyond the schema, though not extensively for the claim parameter itself.

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 as a natural-language claim verification service against authoritative sources, with explicit verb ('verify', 'fact check') and specific resource ('claims'). It distinguishes itself from sibling tools by focusing on claim verification and noting it replaces multi-step sequential calls, making its purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial claims and other facts, routing accordingly. It also mentions it replaces 4-6 sequential calls, implying efficiency, but does not explicitly name alternative tools to avoid, making it slightly less than a 5.

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