Mojang

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: free vs. paid model usage, per-model output structure, and cost implications. 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 (three sentences) and front-loaded with the main action. Every sentence adds value: purpose, default behavior, return format, and use cases. No wasted words.

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

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

Despite no output schema, the description fully explains return values (per-model {score, confidence, signals, raw_response} + combined view). For a 4-parameter tool with simple semantics, this is complete and actionable.

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 value by explaining when to use _apiKey (only for Anthropic), default model behavior, and the context parameter's disambiguation role, going beyond schema names.

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: probing LLMs for knowledge about an entity and returning a visibility score. It uses specific verbs ('probe', 'score') and distinguishes itself from siblings by focusing on AI visibility rather than entity profiles or searches.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs. BYO key options. It does not explicitly exclude alternatives but the context is sufficient for an agent to decide when to use 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 indicate read-only, idempotent, and open-world behavior. The description adds valuable context: the tool routes to many sources and returns structured answers with citation URIs. No contradictions.

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

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

The description is front-loaded with the key recommendation and examples. It is efficient but could be slightly more scannable with lists. Overall well-structured and 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 complex routing tool, the description covers what the tool does, when to use it, and what output to expect (structured answer with citations). It is sufficiently complete for its purpose.

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 aliases explained. The description does not add further parameter insight beyond examples, which is adequate but not above baseline.

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

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

The description clearly states the tool's purpose: to answer factual questions using a vast set of verified sources, distinguishing it from web search and other tools. It uses specific verbs ('ask') and resources ('Pipeworx') and lists many domains.

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

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

The description explicitly recommends this tool over web search and provides clear when-to-use criteria with examples. It lacks explicit mention of when not to use relative to other sibling tools, but the context is strong.

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 annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: it explains the extra LLM cost, the exact refusal reasons (not_in_source, no_tool_match, etc.), and the return structure, which 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 dense and front-loaded with the purpose, but it is essentially one long sentence that could be broken up for better readability. Still, every sentence provides value and there is no wasted text.

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

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

Despite having no output schema, the description fully explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also covers cost implications and the underlying routing mechanism, making it complete for a high-stakes tool.

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

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

Schema coverage is 100%, so the description does not need to add much. It clarifies the aliases (q, text, input, query, prompt) but does not provide additional semantic meaning beyond what the schema already offers. A score of 3 is appropriate as the description adds only marginal 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 is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from the sibling tool 'ask_pipeworx' by specifying that it extracts answers using only the tool result, with explicit refusal reasons.

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

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

The description provides explicit guidance on when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with examples like financial verdicts and legal claims. It also explicitly advises to prefer ask_pipeworx for casual lookups.

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 openWorld behavior. The description adds extensive behavioral details: fan-out mechanism, classifier list, resolver contract with match confidence and alternatives, parent event extraction, news fallback handling, safety short-circuits for low-confidence and closed markets, and cancellation rule parsing. It also explicitly warns about trusting analysis only on high-confidence 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 very long and includes many examples and edge-case details. It is front-loaded with the core purpose, but the extensive text may be overwhelming. While each sentence adds value, conciseness suffers. A more condensed version could be more efficient for an agent 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?

Given no output schema, the description comprehensively specifies all return fields: result.market (bid/ask, spread, liquidity, price changes), result.analysis (model probability, edge, kelly fraction, 24h move warning), result.evidence (keyed by source), and resolver contract details. It also covers error states (low-confidence, closed markets, wide spreads) and cancellation rules. The tool's complexity is fully covered.

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 meaning beyond schema: for 'depth', it explains 'quick = 2-3 evidence sources, thorough = full fan-out'; for 'include_raw', it details size implications and use cases for full payloads. These additions help an agent choose parameters wisely.

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 action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and method (pulling Pipeworx data). The description differentiates it from sibling tools like polymarket_arbitrage and ask_pipeworx by emphasizing the all-in-one call and fan-out behavior.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies when to use over alternatives, but does not explicitly state when not to use or list alternative tools for different scenarios. The examples and detailed fan-out guidance give clear context for usage.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, read-only, idempotent behavior. The description does not contradict these annotations. However, it adds minimal behavioral context beyond stating the action (list), so it scores a 3—adequate but no extra value.

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 (five words) and front-loaded. Every word contributes to the purpose. It could be slightly more informative (e.g., adding 'returns a list of SHA1 strings') but remains efficiently structured.

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

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

Given zero parameters and an existing output schema (which likely describes the return format), the description is complete enough for a simple list tool. The openWorldHint annotation suggests the list may be dynamic, but the description doesn't need to elaborate further.

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 tool has 0 parameters, and the schema coverage is 100% (with only examples). The description adds meaning by specifying that it lists SHA1s, which is the expected output. For a param-less tool, the baseline is 4, and the description sufficiently clarifies the return type.

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

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

The description 'List blocked-server SHA1s' is a single sentence that clearly identifies the tool's purpose: listing SHA1 identifiers of blocked servers. It uses a specific verb (list) and resource (blocked-server SHA1s), distinguishing it from siblings like 'recent_alerts' or 'recent_changes'. However, it does not provide additional context on what 'blocked' means or how these SHA1s are generated.

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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or any scenario where this tool is preferred. Given the lack of usage context, the agent has no direction on appropriate invocation conditions.

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

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

Adds significant behavioral context beyond annotations: describes data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradiction with annotations.

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

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

Single paragraph is information-dense and front-loaded with trigger phrases. While effective, it could be slightly more structured (e.g., bullet points) for easier scanning.

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?

Completely addresses the tool's complexity: explains return format (paired data + citations), sorting behavior, and efficiency gain (replaces 8-15 lookups). No output schema exists, but description sufficiently covers 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 coverage is 100%, but description enriches parameter understanding by providing concrete examples (e.g., tickers, drug names), explaining what each type pulls, and noting handling of fiscal years.

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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific examples of trigger phrases and distinguishes itself from sequential lookups.

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

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

Explicitly instructs to prefer over sequential single-pack lookups when comparing entities. Provides clear context for when to use, but does not explicitly list alternative tools for single entity lookups.

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 behavioral details: returns explicit gaps[] for unanswerable facets, never invents, facts are pre-verified, and mentions parallel execution. 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 key benefit. Every sentence adds value, though it could be slightly more concise. Still, it is well-structured and informative.

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, the description covers inputs, behavior, limitations (gaps, no invention), prerequisites, timing, and output structure. Even without an output schema, it clearly explains the return format (findings packet with evidence, confidence, etc.).

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 meaningful context: explains depth enum values (quick=3, standard=5, thorough=8) and that question should be natural language (broad/multi-part fine). This adds value beyond the schema.

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

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

The description states a specific verb ('multi-source research') and resource ('one call'), with clear explanation of decomposition and parallel execution. It explicitly distinguishes from sibling 'ask_pipeworx' by contrasting use cases (broad vs. single lookup).

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

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

Explicit guidance on when to use (broad/multi-part questions) and when not (single lookups, for which ask_pipeworx is recommended). Also specifies prerequisites (Pipeworx account, paid plan for 'thorough' depth) and expected timing (15-60s).

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing what is returned (top-N tools with schemas) and highlighting that results are ready to call without a second lookup, which is useful behavioral context beyond annotations.

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

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

The description is informative and front-loaded with the core purpose. It includes a list of data types and return characteristics, which is helpful. A bit long but every sentence contributes value; 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?

Given the meta-tool nature and full schema coverage, the description sufficiently explains what the tool does, when to use it, and what it returns. No output schema is needed as the return structure is clearly described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter-specific meaning beyond what the schema provides, but it does clarify the overall behavior of query aliases and default/max limit values mentioned in the 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's purpose: to find tools by describing data or task. It lists specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself as a discovery tool, contrasting with sibling tools that perform specific tasks.

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

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

It explicitly advises using this tool FIRST when many tools are available, indicating a prioritized usage context. While it doesn't list when not to use or compare to specific siblings, the guidance is sufficient for an AI agent to understand its role in the workflow.

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=false. The description adds behavioral details: fans out across multiple sources, soft-fail for patents API, fallback for news, and specific return structure. 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 dense with valuable information and front-loaded with example queries. Every sentence adds utility, but it is somewhat long and could benefit from bullet points for readability.

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

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

Despite lacking an output schema, the description thoroughly explains all returned fields and their sources. It covers parameters, behavioral traits, fallbacks, and usage tips, making it complete for the agent.

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

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

Schema coverage is 100% with descriptions. The description adds additional context: names not supported, ticker vs CIK formats, zero-padded CIK, and explicit example values. This significantly enhances parameter understanding.

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

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

The description clearly states the tool provides a holistic cross-source profile of a US public company, listing specific sources and returned data fields. It distinguishes from siblings like 'compare_entities' and 'resolve_entity' by focusing on a single entity profile.

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

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

The description explicitly prefers this tool over chaining single-source lookups for holistic queries and advises using resolve_entity first if only a name is available. However, it could mention when not to use (e.g., for non-US companies or non-company entities).

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 destructiveHint=true and idempotentHint=true, so the description adds context by mentioning clearing 'sensitive data' and stale context. It does not contradict annotations and complements them with practical use cases.

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 highly concise: two sentences that state purpose and usage guidance without any filler. Every sentence adds value, making it easy to parse quickly.

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 is complete for a simple deletion tool, covering purpose and usage context. It does not mention error handling or return values, but given the tool's simplicity and idempotent hint, this is not critical. Still, a brief note on idempotency would enhance completeness.

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

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

The schema covers the single parameter 'key' with description 'Memory key to delete' (100% coverage). The tool description does not add further detail about the parameter, so it meets the baseline but does not exceed it.

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

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

The description clearly identifies the tool's action: 'Delete a previously stored memory by key.' It distinguishes itself from siblings by specifying the delete operation and explicitly mentioning pairing with 'remember' and 'recall'.

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

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

The description provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also advises pairing with related tools, helping the agent decide when to apply the tool.

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

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

Description adds significant behavioral context beyond annotations: it explains the process (fetch page, extract title/description/key links, emit standard markdown format) and output (single text blob ready to drop at site-root/llms.txt). Annotations already indicate safety and idempotency; description complements 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?

Description is compact (two sentences plus a bulleted list of use cases) and front-loaded with the core purpose. Every sentence adds value with no redundancy.

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

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

Tool is simple with 2 parameters and no output schema; description fully covers purpose, process, output format, and use cases. It is complete and addresses all relevant aspects for correct invocation.

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 description adds minimal extra meaning to parameters beyond what's in schema. It does not elaborate on parameter usage beyond the process description, but the schema descriptions for url and max_links are already informative. 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?

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and context (AI crawlers). It distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than visibility scanning.

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?

Description explicitly lists use cases (getting client's site indexed, drafting own llms.txt, auditing competitor visibility), which helps the agent decide when to use the tool. However, it does not mention when not to use it or contrast with alternatives among siblings, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, etc. The description adds that it returns specific fields and scope (caller's active), but no additional behavioral traits beyond annotations.

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

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

Two sentences with no fluff, efficient and front-loaded.

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

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

For a simple list tool with one optional param, the description is sufficient; it covers purpose, returns, and usage, but lacks details on sorting or limits.

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 no extra parameter info beyond what the schema already provides.

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

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

The description clearly states it lists the caller's active subscriptions, specifies returned fields, and is distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly says to use it before adding more subscriptions or to find an id to cancel, providing clear context, though it doesn't mention 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 declare read-only and non-destructive behavior. The description adds no further behavioral context (e.g., output format or pagination), but the safety profile is covered by 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?

Extremely concise: a single phrase. It is not verbose but lacks proper sentence structure and is somewhat under-specified.

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 an output schema present, return values need not be detailed. However, the description omits what kind of name changes (e.g., username or display name) and temporal scope, leaving some ambiguity.

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 0%, and the description does not explain the meaning of 'uuid' (e.g., user or entity ID). It adds no value beyond the parameter name 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 'Historical name changes' indicates the tool returns past name changes for an entity identified by uuid. It is clear but not highly specific; however, it distinguishes from sibling tools like entity_profile.

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

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

No guidance on when to use this tool vs alternatives (e.g., entity_profile). The description lacks any context about prerequisites or recommended scenarios.

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

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

The description adds key behavioral details beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that team reads digests daily. No contradiction with annotations (all false).

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 single paragraph, front-loaded with purpose, followed by usage, limitations, and team context. Every sentence adds unique value with no redundancy.

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

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

Despite no output schema, the description covers input requirements, rate limits, impact, and user guidance. It is fully complete for a feedback tool with simple nested parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by elaborating on the type enum meanings and emphasizing specificity in the message, slightly above baseline.

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

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

The description uses a specific verb ('Tell') and resource ('Pipeworx team') and clearly states the tool's purpose: reporting bugs, requesting features, or giving praise. It is distinct from sibling tools which are all operational or informational, not feedback.

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 for each feedback type (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and that it's free, with no ambiguity.

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

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

Discloses data source (CF analytics-engine), no PII, caching behavior (5min-1h), and that it is self-aggregating. Annotations confirm readOnly, idempotent, non-destructive. No contradiction.

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

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

Three sentences, front-loaded with purpose, no fluff. Each 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?

No output schema, but description explains return type (top tools, packs, volume) and caching behavior. Complete for a read-only aggregation tool with one parameter.

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

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

Schema has 100% coverage with enum and description for window parameter. Description adds meaning: shorter windows for hot, longer for steady-state, beyond what schema enum provides.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window. Distinguishes from siblings like ask_pipeworx or discover_tools by being a trending/aggregation 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?

Lists three specific use cases (discovering hot data sources, confirming popular tool, aligning use case). Does not explicitly state when not to use or mention alternative tools, but the examples are helpful.

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

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

The description goes beyond annotations by detailing internal logic: fill check, semantic anchor for cross-event pairs, partition filter, and response structure. It discloses that realizable_edge_pp ≤ 0 means the edge exists only at last-trade and should not be traded. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is quite long but well-structured, starting with the requirement and then explaining modes, algorithm, response, and fill check. Every section adds necessary detail, so it earns its length. Minor improvements could tighten phrasing, but overall it's effectively organized.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers response fields (opportunities, partition_check, fill_check results) and provides actionable guidance (e.g., 'do not trade it' when edge is negative). It also references a sibling tool for complementary functionality, making it self-contained.

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

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

Even though input schema has 100% coverage, the description adds significant value by explaining each parameter's mode (event vs topic), providing examples (e.g., 'fed-decision-may-2026'), and clarifying that event mode can accept full URLs. This enriches the semantic understanding beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes two modes (event and topic). It differentiates from sibling tools like polymarket_fill_risk and polymarket_edges by specifying when to use each, thus providing clear purpose and 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?

The description explicitly explains when to use event mode (specific known market) vs topic mode (cross-event scanning), and directs users to polymarket_fill_risk for custom sizing. It also warns against calling with no args, providing clear usage context and 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds substantial behavioral context: caching at KV level for 1 hour, response structure (by_segment, diagnostics), and details on edge calculations (edge_pp_net, kelly_fraction, 24h-move warning). No contradictions with annotations.

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

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

The description is very long and highly technical, with multiple paragraphs of detailed model explanations. While it front-loads the purpose, it lacks conciseness. Every sentence may be earned for domain experts, but overall verbosity reduces clarity for a general agent.

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

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

Given the tool's complexity (9 parameters, no output schema), the description thoroughly explains the response structure (by_segment with three segments, diagnostics, fed note) and edge calculations. It covers caching, knobs, and why Fed bets are excluded, making it complete for an agent to understand and use.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The description's 'TRADEABLE-EDGE KNOBS' section adds narrative but does not provide significant meaning beyond what the schema descriptions already convey. 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes from siblings like polymarket_arbitrage by focusing on model-driven and structural 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 frames the tool for discovering betting opportunities and provides detailed knob parameters (e.g., min_liquidity, max_spread_pp) that guide when to use it. It mentions Fed bets are excluded from ranking, giving context. However, it does not explicitly state when not to use it compared to siblings.

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

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

Annotations already confirm read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: it reads from daily snapshots, computes trend and decay, and explains the data source limitations. 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 thorough but somewhat lengthy. It front-loads the core purpose and uses clear structure with sections for args, response, and limits. Could be slightly more concise, but 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 no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and limitations. It covers all necessary context for the agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, but the description enriches both parameters: clarifies defaults (days: 14, window: '1wk'), clamps (days: 2-30), and explains that window refers to snapshot family. It also details response fields, adding meaning beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes from siblings by focusing on time-series analysis of 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 implies when to use (e.g., comparing fresh vs old edges) and mentions limitations like the 60-day TTL and dependency on cache-miss snapshots. However, it does not explicitly differentiate from sibling tools like polymarket_edges or provide 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?

The description discloses behavioral traits beyond annotations: it describes walking the ladder, returning specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and the risks of partial basket fills. It does not contradict the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 with section headers (SINGLE-MARKET, BASKET) and uppercase emphasis for key points. It front-loads the main purpose and every sentence adds necessary detail, though some redundancy could be trimmed.

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

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

Despite the tool's complexity (two modes, many return fields, no output schema), the description lists all important return fields for each mode, explains the verdict system, and covers edge cases like thin legs and forced directional risk. It provides sufficient information for an agent to understand inputs, behavior, and outcomes.

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 significant context: explaining that `market` and `event` are mutually exclusive, detailing default modes and interpretation of `size_usd` in both modes, and clarifying the `side` parameter's auto-detection in basket mode. This adds value beyond the schema's own descriptions.

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

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

The description clearly states the tool's function as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It is specific about the verb ('check') and resource ('Polymarket orders'), and it differentiates itself from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: before acting on arbitrage signals or trades above ~$500. It warns against relying on theoretical overround on thin books and explains risks like partial fills converting to unhedged positions, providing clear context and 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral details: modes, response structure, compatibility warnings, temporal alignment, and counters. 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 detailed but well-structured with clear sections. A few repetitive phrases ('pre-mapped ≠ tradeable') but overall efficient for the complexity.

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

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

Despite no output schema, the description fully compensates by detailing response fields (raw probabilities, spread, safety fields, temporal alignment, counters) and edge cases (compatibility warnings, skipped comparisons).

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

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

Schema coverage is 100% with descriptions. The description adds context by explaining how topic shortcuts work and that explicit parameters override the topic. Slightly more explanatory than schema alone.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket. It explains the two modes and contrasts with sibling tools like polymarket_arbitrage by focusing on the same resolving question across venues.

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

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

Explicitly describes two usage modes (topic shortcuts or explicit identifiers) and warns that most pre-mapped topics are not tradeable due to compatibility warnings. Provides clear when-to-use and 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 are rich (readOnlyHint, idempotentHint, etc.), but the description adds minimal behavioral context beyond 'name + textures'. It does not disclose whether the tool requires authentication, latency considerations, or any side effects. Since annotations already indicate safety, the description fails to add value.

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?

While very short, the description is under-specified rather than concise. It omits critical information about purpose and parameters, making it less useful. Every word must earn its place; here, 'Profile (name + textures)' provides only a hint.

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 single parameter, rich annotations, and existence of an output schema, the description should clarify the tool's scope and result. 'Name + textures' is insufficient; it leaves ambiguity about what textures are (e.g., skins, capes) and whether the tool returns only those fields or more. It is incomplete for its context.

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 1 parameter 'uuid' with no description (0% schema coverage). The tool description does not explain what 'uuid' expects (e.g., a player UUID, profile UUID) or how it relates to 'name + textures'. This leaves the agent guessing about the parameter's meaning and format.

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

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

The description 'Profile (name + textures)' is vague. It does not explicitly state a verb like 'retrieve' or 'get', and it's unclear whether it creates, reads, or updates. The parenthetical adds some specifics but the overall purpose is ambiguous, especially compared to sibling 'entity_profile' which suggests a similar function.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when to choose this over sibling tools like 'entity_profile' or 'resolve_entity'.

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 behavior details: listing all keys when omitted, scoping to identifier, and pairing with companions. Adds value beyond annotations.

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

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

Two efficient sentences that front-load the main action. Every sentence earns its place; no wasted words.

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

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

Complete for a simple tool with full schema and annotations. Covers both use cases, scoping, and companion tools. No missing information.

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%. Description expands on the key parameter by explaining the dual behavior (retrieve vs list all when omitted). Adds meaning beyond schema description.

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

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

Clearly states the tool retrieves a saved value or lists all keys, differentiating between the two modes. Specific verb+resource, and distinguishes from siblings '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 context: use to look up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget. Could contrast more with other siblings but is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: that mark_read:true flags events as read so subsequent calls return only newer ones, and that the tool returns source, citation_uri, and raw payload. 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, well-structured paragraph of about 4 sentences. It front-loads the core purpose, then efficiently covers parameters and behavior. Every sentence adds value, and there is no redundant or filler content.

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

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

Given there is no output schema, the description adequately describes the return fields (source, citation_uri, raw payload). It covers all parameters, provides usage context (polling, alternative endpoint), and addresses the mark_read stateful behavior. No gaps remain for an effective first-time usage.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description enhances meaning by providing examples (e.g., "sec_8k" for type), clarifying the format for since (ISO timestamp), and explaining the effect of mark_read and unread_only. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns most recent alerts with specific fields (source, citation_uri, raw event payload), and supports filtering by type and since timestamp. It distinguishes itself from siblings like list_subscriptions by focusing on alert retrieval.

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

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

The description provides explicit context: it mentions that polls work fine for repeated usage, and directs users to an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. This gives clear guidance on when to use this tool versus other means.

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. The description adds critical behavioral context: parallel fan-out, fallback logic (GDELT preferred, GNews on rate limits), USPTO soft-failure until May 2025, and return structure with citation URIs. No contradictions.

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

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

Single paragraph, front-loaded with examples, then source details, parameter guidance, and alternative tool. Every sentence adds value; no redundancy or filler. Highly efficient.

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

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

Despite no output schema, the description fully explains return values (changes[] grouped by source, total_changes, pipeworx:// URIs). It covers edge cases (GDELT fallback, USPTO soft-failure), parameter formats, and usage boundaries. Complete for a complex multi-source tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds value beyond schema by explaining relative shorthand meanings ('7d', '30d', '3m', '1y'), recommended default ('30d'), and that 'value' accepts ticker or zero-padded CIK. Misses explicit type constraint only on enum.

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

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

The description explicitly states the tool provides a change feed for a company, listing specific verbs like 'what's new', 'latest on', 'updates on'. It details the data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from sibling 'entity_profile' by contrasting dynamic vs static profiles.

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

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

The description provides explicit when-to-use guidance, including example queries. It directly contrasts with 'entity_profile': 'Use entity_profile instead when you want the static profile... regardless of window.' It also recommends typical parameter values like '30d' for monitoring.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds context about persistence: authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradictions; additional transparency on scope and lifespan.

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 concise at 3 sentences. First sentence states purpose, second gives usage context, third covers behavioral details. No wasted words.

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

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

Despite no output schema, description fully covers storage semantics, scope, and pairing with siblings. Complete for a simple key-value store 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 both parameters with description. Description adds naming convention examples for key and clarifies value is 'any text — findings, addresses, preferences, notes', complementing the schema.

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

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

Description clearly states the tool saves data for later reuse, specifying 'Save data the agent will need to reuse later'. It distinguishes from sibling tools like recall and forget by mentioning pairing.

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

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

Explicit when-to-use guidance: 'Use when you discover something worth carrying forward'. Also tells when not 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 indicate read-only, idempotent, and non-destructive behavior. The description adds value by noting that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This contextualizes the tool's internal complexity without contradicting annotations.

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

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

The description is front-loaded with common user question patterns, followed by usage guidance and supported types. Every sentence provides distinct value. It is slightly longer than necessary but remains focused and well-organized.

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

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

Given only 2 parameters, no output schema, and rich annotations, the description comprehensively covers input format variations, entity types, and internal behavior (cascading lookups). It leaves no obvious gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% (both parameters described), so baseline is 3. The description adds examples for each 'type' value (e.g., for company: ticker, CIK, or name; for drug: brand or generic name), clarifying acceptable input formats beyond the schema's short descriptions.

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

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

The description clearly identifies the tool's purpose: resolving a user-spoken name to a canonical identifier. It provides specific verb phrases and examples of user queries (e.g., 'What's the ticker for…'). The tool is distinguished from siblings by listing supported entity types and the exact outputs (ticker, CIK, RxCUI, etc.).

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. However, it does not specify when not to use the tool or mention alternatives among siblings (e.g., compare_entities, entity_profile), which slightly limits 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already declare safety profile. Description adds behavioral context: probes each entity, returns ranked list with score/confidence/signal density. No contradictions with annotations. Additional info on auth requirements via _apiKey parameter described in schema.

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 efficient sentences with zero waste. Core action front-loaded in first sentence. Example question provides immediate clarity. No redundant information.

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

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

Despite no output schema, description specifies return format (ranked list with score, confidence, signal density per entity). Parameter count and required fields are clear. Context of competitive audit is fully explained. No gaps for this tool's complexity.

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

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

Schema description coverage is 100%—all four parameters have detailed descriptions. Description adds collective meaning: 'Probes each entity...returns ranked list...' which contextualizes the parameters as part of a side-by-side comparison. Baseline 3 elevated due to narrative that ties parameters to a use case.

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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. Verb 'compare' and resource 'AI visibility' are specific and distinguishable from sibling tools like ai_visibility_check (single entity probe) and compare_entities (likely different comparison type).

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

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

Provides explicit usage context: 'useful for competitive AI-marketing audits' and illustrative example question. Implicitly suggests when not to use by describing internal use of ai_visibility_check, hinting that single entity probes should use that sibling instead. However, lacks explicit 'when not to use' or direct alternative naming.

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 specific behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts. It also describes the return format (summary block, per-advisory detail, links, alternative versions). 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?

Description is front-loaded with the main purpose and use cases. It is well-structured but somewhat verbose (6 sentences). Every sentence adds value, but could be slightly tightened. Still, it meets the standard of earning 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?

With no output schema, the description fully explains all return fields (summary block fields, per-advisory detail, links, alternative versions). Also covers timing behavior, partial failure, and ecosystem limitations. For a complex tool with 2 params, this is very 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%, both parameters have descriptions. The description adds no new parameter semantics beyond what the schema already provides (e.g., 'Defaults to the latest published version when omitted' is in both). The mention of scoped packages is identical. Baseline 3 is appropriate as schema does all the work.

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's a composite check for npm packages across deps.dev and bundlephobia, with a specific verb 'scan' and resource 'dependency'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on npm packages and project health.

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

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

Explicitly tells when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details the embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K with truncation flag), and output format (passages with offsets and similarity scores). 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 substantive but not verbose. Each sentence contributes unique information (purpose, usage, pairing, technical details). Could be slightly tighter but still efficient.

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

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

Given the complexity of semantic search and no output schema, the description covers all key aspects: input constraints, expected output, technical implementation, and integration with a sibling tool. An agent can infer how to use it and 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 coverage is 100%, so baseline is 3. The description adds value with concrete examples for the query parameter (e.g., 'supply-chain risk') and reinforces the purpose of text and limit, improving usability.

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 verb 'search' and resource 'inside a fetched record' are specific and unambiguous. The description differentiates from siblings by specifying it works on already-pulled text, contrasting with tools like ask_pipeworx_grounded.

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

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

Explicitly states when to use: when the record is too large for the prompt. It also provides a workflow pairing with ask_pipeworx_grounded. While it does not list explicit when-not scenarios, the context is clear.

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

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

Annotations indicate write operation, open world, idempotent, non-destructive. The description adds context: returns new subscription ID, delivery channel behaviors (SMS cap, webhook auto-disable), and requires OAuth. Idempotency not explained (e.g., duplicate subscription behavior), but otherwise 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?

Well-structured, starting with main purpose then requirements, types, delivery. Dense but each sentence adds value. Slightly long but appropriate for complexity. No unnecessary 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?

Comprehensive coverage of types, delivery options, prerequisites, and constraints (SMS cap, webhook auto-disable). Missing return format beyond subscription ID, but no output schema exists. Overall adequate 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% and description adds substantial value: explains type-specific params with examples (e.g., sec_8k items, polymarket_edge topic, delivery constraints like phone verification and webhook signing). Provides usage context 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 action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the resource and returns a subscription ID. Distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by detailing subscription creation versus listing or removal.

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

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

Explicitly describes when to use (proactive monitoring), prerequisites (OAuth account, phone verification for SMS), and types. Implicitly distinguishes from alternatives (e.g., 'recent_alerts' for pulling fired alerts). Could be more explicit about when not to use, but clear overall.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by detailing the return format (category-bucketed examples with tool+argument shapes) and behavior differences with/without a topic argument. No contradictions found.

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

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

The description is lengthy but every sentence earns its place. It front-loads the primary purpose, then lists categorized examples and usage variations. Slightly verbose but well-structured.

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

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

Given the tool's single optional parameter and no output schema, the description fully explains what the tool returns, how arguments affect output, and its role relative to siblings. No gaps identified.

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

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

Schema coverage is 100% (1 parameter described). The description adds meaning by listing example topic values (e.g., 'finance', 'pharma') and explaining that omitting topic returns a cross-category spread, which is not in the schema.

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

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

The description clearly states the tool returns category-bucketed example questions and explicitly distinguishes itself as the onboarding entry point for agents unfamiliar with Pipeworx. It uses specific verbs like 'returns' and lists sibling meta-tools, making the purpose unambiguous and differentiated.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear context for when to invoke. It also mentions learning how to call meta-tools like ask_pipeworx, implying alternatives without formal when-not guidelines.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available, adding context beyond annotations which only indicate non-destructive mutation.

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 action. Every word earns its place with no redundancy.

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

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

For a simple mutation tool with one well-documented parameter and annotations, the description sufficiently covers behavior (ownership, deactivation) and outcome. Lacks details on error cases but adequate for typical use.

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

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

Schema already fully describes the id parameter (100% coverage). Description adds no additional meaning beyond 'by id', so it meets baseline but does not exceed.

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 the specific verb 'cancel' with resource 'subscription by id', clearly distinguishing from siblings like 'subscribe' 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?

States ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. No explicit comparison to alternatives, 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 already declare readOnlyHint, idempotentHint, etc. The description adds 'current' to indicate temporal scope, but does not disclose behavior like case sensitivity or error handling. Adds marginal value beyond annotations.

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

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

The description is a single concise sentence with no wasted words. However, it is overly terse and sacrifices completeness for brevity.

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 tool (1 param), rich annotations, and existence of an output schema, the description is minimally complete. It could be improved by adding usage examples or clarifying the return format, but is acceptable for the low complexity.

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

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

The input schema has 0% description coverage for the single parameter 'username'. The description does not explain the parameter's meaning, format, or constraints, leaving the agent without necessary context.

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

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

Description clearly states the tool retrieves the current UUID for a given username, using an implied verb 'get' and specific resource. However, it does not differentiate from the sibling tool 'username_to_uuid_at', which provides historical UUIDs.

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

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

No guidance on when to use this tool versus alternatives like 'username_to_uuid_at'. The description lacks context for usage, leaving the agent to infer from the name alone.

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 minimal behavioral context beyond the annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description carries a lower burden. However, it does not explain expected outputs (e.g., what happens if the username is not found at the given timestamp) or any edge cases.

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 extremely short (one sentence) but lacks essential information about the tool's operation. Conciseness should not sacrifice completeness; here it is under-specified.

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 two parameters, no schema descriptions, and an output schema (not shown), the description should cover basic functionality and parameter roles. It fails to do so, leaving the agent without enough context to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at the timestamp parameter with 'epoch second' but fails to describe the username parameter or clarify that timestamp is optional. This is inadequate for understanding parameter meaning.

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

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

The description 'UUID at a given epoch second' does not explicitly state the main purpose of converting a username to a UUID. It mentions the output and a specific input parameter but lacks a clear verb and resource definition. The title name_to_uuid_at implies conversion, but the description itself is vague.

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

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

No usage guidance is provided. There is a sibling tool 'username_to_uuid' that likely performs the same conversion without a timestamp, but the description does not differentiate between them or suggest when to use this tool over 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, idempotentHint, and destructiveHint as true/false. The description adds valuable behavioral context: it specifies the supported domain (company-financial claims via SEC EDGAR + XBRL), the return structure (verdict, structured form, citation, delta), and notes it replaces 4–6 sequential calls. This goes beyond annotations without contradicting them.

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

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

The description is well-structured with a clear opening that lists natural-language triggers, followed by usage guidance, scope details, output summary, and efficiency notes. Every sentence adds value without redundancy, making it concise yet comprehensive.

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

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

Given the tool has a single parameter and no output schema, the description adequately covers what the tool does, when to use it, and what to expect (verdict types, citation, delta). It is complete for the agent's needs, though a bit more detail on input validation (e.g., claim format) could be added.

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

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

The input schema has 100% coverage with a single parameter 'claim' described with examples. The description further adds domain specificity, explaining it supports company-financial claims. Since the schema already does a good job, the description enhances understanding but is not essential beyond what the schema provides.

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

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

The description clearly states the tool is for natural-language claim verification against authoritative sources, with examples like "fact check" and "verify the claim." It distinguishes itself from sibling tools like 'entity_profile' or 'bet_research' by focusing on factual correctness rather than entity lookup or betting odds.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This provides clear context. However, it does not explicitly mention when not to use or provide alternative sibling tools, but the context is sufficiently clear for an agent to infer usage.

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