Maven Central

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context: it probes LLMs, returns a visibility score (0-100), per-model results, and mentions cost implications for Anthropic. This goes beyond annotations and fully informs the agent about behavior.

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

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

The description is concise—4 sentences with no redundancy. The main purpose is front-loaded, followed by key details (default model, Anthropic option, return structure, use cases). Every sentence is informative and earns its place.

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

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

Despite lacking an output schema, the description explicitly states the return structure (per-model object with score, confidence, signals, raw_response plus combined view). All four parameters are described in the schema, and the description adds enough context for correct invocation. The tool's moderate 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 coverage is 100% with good descriptions for each parameter. The description adds semantic value by clarifying the default model, explaining the optional _apiKey purpose, and providing example values for 'entity' and 'context'. This provides a baseline of 3, and the extra usage hints raise it to 4.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource (LLM visibility for a brand/product/topic). It distinguishes from siblings by specifying the use case: AI-marketing audits, pre-launch brand checks, competitive monitoring, which are not covered by other tools like 'search' or '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?

Provides clear context for when to use (visibility audits) and explains the default model and the optional Anthropic probe with BYO key. While it doesn't explicitly list alternatives, the specificity of the use case implicitly guides selection. Minor improvement would be to mention when not to use (e.g., for general search or entity details).

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

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

Annotations already declare read-only, idempotent, open-world. The description adds valuable behavior: routes to 5,529 tools, fills arguments, returns pipeworx:// citation URIs, works on every tier, one fast call. No contradiction with annotations, and this context goes beyond what annotations provide.

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

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

The description is long but efficiently structured: opening recommendation, supported domains, behavior, trigger phrases, examples, and escalation guidance. It's front-loaded with the most critical 'PREFER OVER WEB SEARCH' callout. Some redundancy exists, but each section adds distinct useful information.

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

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

For a high-complexity tool with no output schema, the description covers use cases, alternatives, citation behavior, data domains, examples, and when to escalate to sibling tools. It thoroughly addresses the agent's need to understand when and how to invoke this tool correctly.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description provides examples and trigger phrases but doesn't add new semantic detail about the parameters beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: answering factual questions by routing to thousands of sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly positioning as the default entry point and by comparing to ask_pipeworx_grounded and deep_research.

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

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

Gives explicit when-to-use guidance with trigger phrases ('what is', 'look up', etc.), says to 'PREFER OVER WEB SEARCH', and provides step-up alternatives (ask_pipeworx_grounded for grounded answers, deep_research for broad questions). Also clarifies that breaking-news queries are handled directly.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is a full working router with no fallback, candidate routing changes are enabled live during tests, and results are compared against the stable router. This goes beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the beta identity. While it repeats the idea of matching ask_pipeworx a couple of times, each sentence contributes useful information about behavior, current status, and usage.

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 then tool's moderate complexity, no output schema, and strong annotations, the description fully covers the experimental nature, relationship to the stable router, current equivalence, and absence of fallback. The agent has enough context to use it correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the question field. The description does not need to add parameter details; the schema already provides complete semantics. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, specifying it is a universal router with the same 5,529 tools and same arguments. It distinguishes itself from the stable sibling by noting candidate routing improvements and its experimental edge.

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 the agent to use it exactly like ask_pipeworx when wanting the newest routing, names the stable alternative, and explains the comparison process. It also clarifies the current state (no active candidate) so the agent knows it currently matches the stable router.

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

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

The description goes far beyond the annotations by detailing the exact return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}), explicit refusal reasons (not_in_source, no_tool_match, etc.), and the additional cost of one extra LLM call. It also clarifies the grounding methodology (only using tool result content), which is not captured by readOnly/idempotent hints.

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

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

The description is dense but every sentence contributes value: purpose, mechanism, return contract, use cases, and cost tradeoff. It is well-structured, starting with the core value proposition and then expanding into behaviors, making it efficient and information-rich without redundancy.

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

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

Despite having no output schema, the description explicitly defines the success and refusal return structures, covers failure modes, and explains the cost differential. It also places the tool in context relative to ask_pipeworx and provides concrete use cases, making it fully self-contained for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question', and the schema already fully explains parameter semantics. The description adds no parameter-specific meaning beyond what the schema provides, so a baseline of 3 is appropriate since the schema carries the burden effectively.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with specific verb/resource ('extracts the answer using ONLY what the tool result contains') and distinct scope. It also distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and tradeoff, leaving no ambiguity about its 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?

Explicit guidance states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), with concrete examples like financial verdicts and legal claims. This directly addresses alternatives and provides actionable selection criteria.

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

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

Disclosures far exceed annotations. Details resolution pipeline, fan-out logic, confidence matching, parent event extraction, news fallback, safety short-circuits, spread warnings, and cancellation rule parsing. ReadOnlyHint is confirmed; 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?

While comprehensive, the description is dense and lengthy (multiple paragraphs). However, it is front-loaded with a clear summary and uses sectioning (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to aid 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?

Despite no output schema, the description fully details response structure: result.market, analysis, evidence, market_match_confidence, parent_event, news fields, and error/safety cases. No gaps remain for an agent to infer.

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 3 parameters. Description adds value: explains market input formats (slug, URL, question), depth defaults, and include_raw behavior. Clear examples further aid selection.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools (e.g., search, validate_claim) and provides concrete examples.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also implies when not to use (e.g., generic research) and lists alternatives in sibling tools.

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

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

Adds significant context beyond annotations: explains data sources, fiscal year handling for companies (off-calendar handled correctly), sorting by primary metric, and return format (paired data + citation URIs). Annotations already indicate readOnly/openWorld/idempotent, and description aligns with these.

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 dense but efficient, front-loading example queries and using shorthand like 'AAPL Sep, NVDA Jan'. Every sentence serves a purpose, stating scope, data sources, sorting, and return format. No fluff.

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

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

Despite no output schema, description sufficiently explains return data (paired results, sorted by metric, with citation URIs). For a complex comparison tool with two entity types and multiple data sources, the description covers all key behavioral aspects, making it complete for agent 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%, but description adds meaning: explains that type='company' pulls financials and type='drug' pulls adverse-event/trial data, and how to format values (tickers/CIKs for companies, names for drugs). This is beyond the schema's enum and array 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?

Description explicitly states it performs side-by-side comparisons of 2-5 companies or drugs, specifying data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). Clearly distinguishes from sibling tools like entity_profile, which likely provides single-entity deep dives.

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 concrete usage examples 'Compare X and Y', 'which is bigger', and explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance and when-not-to (avoid sequential 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 readOnly/openWorld/idempotent/non-destructive, but description adds substantial beyond-annotation context: account requirement and paid tier for 'thorough', the internal decomposition and parallel routing, the findings packet structure with gaps[], the guarantee of not inventing answers, citation fetchability, semantic excerpting, and timing expectations. 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?

Long but every sentence earns its place: prerequisites, exclusions, mechanism, return format, timing, and limitations are densely packed without repetition. The opening line front-loads the critical account requirement, and the use of semicolons and short sentences keeps it scannable.

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

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

No output schema exists, so the description carries full burden for return expectations. It thoroughly covers the findings packet (verbatim evidence, confidence, source, fetched_at, citations), gaps[], contradictions[], hop field, timing, and what happens for off-catalog topics. This is exceptionally complete for a research tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful value to 'depth' by explaining the strategic intent behind each mode (gap recovery, chasing leads) and to 'question' by explicitly inviting 'broad/multi-part' questions. It also clarifies that thorough requires a paid plan, 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 opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call'. It explicitly contrasts with 'open-web search' and distinguishes itself from sibling ask_pipeworx. The scope is precise and unambiguous.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also explains depth-level selection with concrete behavioral consequences like 'standard re-angles unanswered gaps'.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond what annotations provide.

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

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

The description is comprehensive but not overly verbose. It is front-loaded with the core purpose, then provides usage guidance, domain examples, return format details, and strategic advice. Every sentence earns its place, though the domain list is lengthy but necessary.

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 purpose (discovery), parameter count, and absence of output schema, the description covers all essential aspects: when to use, what to expect, how results are structured, and strategic guidance. It is complete for the intended use case.

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 listing example queries and providing a list of data domains, which helps the user understand what kinds of queries are appropriate. It also mentions aliases (though already in schema). This 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's purpose as 'Find tools by describing the data or task', using a specific verb and resource. It distinguishes itself from sibling tools by explicitly being for discovery and browsing, and lists numerous data domains, making it clear what it covers.

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

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

The description explicitly tells when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and provides strategic advice: 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear context and differentiates from other tools.

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

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

The description details that the tool fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and discloses a known limitation: 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'. Annotations already declare readOnlyHint=true and idempotentHint=true, which the 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?

The description is slightly verbose but front-loaded with clear examples and core purpose. Every sentence adds value, though the inline enumeration of returns could be streamlined. Still, it's well-structured and efficient for the complexity.

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

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

Given the tool's complexity (multiple data sources, 2 required params, no output schema), the description covers usage, limitations, fallback behavior, and return fields. It lacks explicit indication of which fields are guaranteed vs optional, but is otherwise comprehensive for agent decision-making.

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

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

Schema coverage is 100%, but the description adds critical context: the 'type' parameter has only 'company' supported now with future plans, and the 'value' parameter explains ticker vs CIK format and reiterates that names are not supported. 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 explicitly states it provides a full cross-source profile of a US public company, with numerous usage examples like 'tell me about X' and 'company profile for Microsoft'. It clearly distinguishes itself from siblings like resolve_entity (name resolution) and compare_entities (comparison), making its purpose unambiguous.

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

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

The description instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving clear when-to-use guidance. It also explicitly states that names are not supported and directs to 'use resolve_entity first if you only have a name', providing a specific exclusion and alternative.

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 destructiveHint=true, and description confirms deletion. Adds context on why deletion is performed (stale context, done task, clear sensitive data), aligning 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?

Two sentences provide all needed information without fluff. Front-loaded with the main action.

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, no output schema, no nested objects), the description fully covers purpose, usage, and behavior.

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

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

Schema coverage is 100%, and description mentions 'by key'. The parameter description in schema already defines it as 'Memory key to delete', so description adds minimal extra meaning.

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

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

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

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', indicating context.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description reveals that it fetches a page, extracts title/description/key links, and outputs standard markdown. This adds valuable behavioral context.

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

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

Three sentences, no fluff, front-loaded with main action. Every sentence provides value: function, process, and use cases.

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 simple parameters and no output schema, the description adequately explains output format ('single text blob', 'standard llms.txt markdown'). Could mention that output is plain text, but sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no new meaning beyond schema for either parameter; it only implicitly references 'url' via 'Fetches the page'.

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 specifies a clear verb ('Generate') and resource ('llms.txt file for any URL'), and differentiates from siblings by focusing on AI crawler indexing. It is not a tautology and provides concrete details.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), giving context for when to use. Does not explicitly state when not to use, but the positive guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds minimal extra context (it returns a release version). It does not describe the output format or any side effects, but annotations cover safety.

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 concise, fitting into a single sentence. While it is efficient, it risks being under-specified. Every word is necessary, but more detail could be added without harming conciseness.

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

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

The tool is simple with two parameters and an output schema. The description covers the core purpose, but fails to provide context about the return structure (though output schema fills this) or usage scenarios. It is minimally adequate but could be more 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?

The input schema has 0% description coverage, so the description must compensate. It only mentions 'groupId' and 'artifactId' in a template phrase, without explaining their meaning, format, or restrictions. The examples in the schema partially help, but the description itself adds little value.

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

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

The description clearly states the tool returns the most recent release version for a given groupId and artifactId. It is specific and distinguishes from the sibling 'list_versions' (which lists all versions) by focusing on 'latest'. However, it lacks an explicit verb like 'get' or 'fetch'.

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 such as 'list_versions'. The description does not indicate prerequisites, constraints, or 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 readOnlyHint=true and destructiveHint=false, so the description adds value by specifying it lists only active subscriptions by default and the return fields. No contradiction.

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

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

Two sentences: first states action and return fields, second gives usage guidance. No 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?

Lists all return fields (id, type, params, created_at, last_fired_at, fire_count) which compensates for missing output schema. Covers purpose, usage, and default behavior. Could mention pagination or limits, but likely unnecessary for this tool.

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

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

Schema covers the only parameter (include_inactive) with a description. Description adds minimal extra context by saying 'active' subscriptions by default, which relates to the parameter. Schema coverage is 100%, 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?

Clear verb 'List' with specific resource 'subscriptions' and explicit fields (id, type, etc.). Distinguishes from siblings like 'subscribe' and 'unsubscribe' which are write operations.

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 when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides context but no direct 'when not to use' or alternatives beyond implied differentiation from subscribe/unsubscribe.

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, destructiveHint. The description adds minimal extra behavioral context (uses Maven Central Solr GAV core). It does not contradict annotations.

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

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

A single, front-loaded sentence that efficiently conveys the tool's purpose. No unnecessary words.

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

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

Given the tool's simplicity and the presence of rich annotations and an output schema, the description is mostly complete. However, it does not explicitly state that the output is a list of versions, which is minor.

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 33% (only 'rows' has description). The description mentions groupId and artifactId but adds no additional syntax or format details. It partially compensates by clarifying their role, but does not fully compensate for the low schema coverage.

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

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

The description clearly states the verb 'list', the specific resource 'published versions of a Maven artifact', and the identifying parameters. It distinguishes from siblings like 'latest_version' by implying a listing of all versions.

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

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

The description implies usage for listing all versions of a Maven artifact, but does not explicitly state when to use this over sibling tools like 'latest_version' or 'search'. It lacks 'use this when' guidance.

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

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

Beyond annotations (which say nothing about side effects), the description discloses the claim_token flow, rate limit ('5 per identifier per day'), free tool-call behavior, and daily digest roadmap impact. This is rich behavioral context that annotations do not provide.

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

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

Although long, every sentence serves a purpose: purpose, usage, exclusions, token mechanism, rate limits. It is front-loaded with the core purpose and structured so an agent can quickly extract key rules.

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

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

For a tool with 4 params, nested objects, and no output schema, the description fully covers the operational context: how to report, what to avoid, the claim_token lifecycle, and even the expected return format ('returns the status and, once resolved, what actually changed').

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

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

Schema descriptions cover 100% of parameters, but the description adds crucial semantic constraints: claim_token must be used 'with no other arguments', and the conditional behavior of filing without an account. This elevates it above the baseline 3.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the feedback categories (bug, feature/data_gap, praise) and clearly differentiates from sibling research/memory tools.

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

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

Provides explicit when-to-use guidance for each feedback type, and equally explicit when-not-to-use: 'ONLY for tools served by this Pipeworx connection… if the tool came from a different MCP server… file it with that server instead.' Also instructs not to paste end-user prompts, adding practical usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: self-aggregating signal derived from CF analytics-engine, no PII, cached 5min-1h depending on window. This goes well beyond what annotations provide.

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

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

The description is concise: a single introductory sentence followed by a brief list of use cases. Every sentence adds value, no redundancy. Information is front-loaded and well-structured.

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

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

Despite having no output schema, the description explains the return content (top tools, top packs, total call volume), data source, privacy, caching, and parameter behavior. For a simple tool with one optional parameter, this is fully complete.

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

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

Schema coverage is 100% with a description for the only parameter 'window' explaining its enum values. The description adds further semantic value by explaining the trade-off: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the schema's description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window. The verb 'returns' is specific, the resource is 'Pipeworx trending data', and the description distinguishes it from siblings by focusing on popularity metrics rather than search or discovery.

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 lists three use cases: discovering hot data sources, confirming canonical choice, and checking alignment with agent trends. It provides context on when to use, though it does not explicitly state when not to use or list alternatives among siblings, which would push it to a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds critical behavioral context: monotonicity checks, partition checks, fill check against CLOB depth, semantic anchor (Jaccard similarity), partition filter (placeholder slug handling). 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 dense and well-organized, starting with purpose, then modes, then detailed behavior per parameter, then fill check, then sibling reference. However, it is somewhat verbose; some sentences could be compressed without losing meaning (e.g., the semantic anchor explanation). Still, 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?

Despite lacking an output schema, the description thoroughly explains response structure: opportunities array, partition_check object, fill_check details. Covers edge cases (cross-event mode, semantic anchor, partition filter, fill check condition). For a complex tool, this is exceptionally complete.

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

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

Schema description coverage is 100% for both parameters. Description significantly enriches meaning: event accepts slug or full URL, topic is a seed question; details behavior for each mode (e.g., cross-event catches patterns single-event misses). Adds value beyond schema fields.

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

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

The description clearly specifies the tool identifies arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending scan), event (specific market), and topic (cross-event scan). This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: trending scan (no args), specific event (event), cross-event (topic). Also explains when not to trade (fill check condition: realizable_edge_pp ≤ 0). References sibling tool polymarket_fill_risk for custom sizing. Provides clear context and exclusions.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: caching at 1h, internal model details, and limitations (e.g., Fed bets unreliable without paid data). 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 very long and dense, packed with technical details and parentheticals. While informative, it lacks conciseness and clear structure (e.g., no bullet points), making it harder 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?

Given the complexity (9 parameters, no output schema), the description thoroughly explains the response structure (by_segment, diagnostics, fed note) and the behavior of each model family, making it complete for an AI agent to use.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description goes further by explaining nuances like why min_kelly doesn't filter partition arbs and how min_partition_leg_kelly works, adding value beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and it distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing its unique model families and segments.

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

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

The description states it is built for 'what should I bet on today' and helps agents discover opportunities without paging, but it does not explicitly say when not to use or mention alternatives. However, it does note that Fed bets are excluded from ranking, providing a usage boundary.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: return structure (tracked, expired, snapshot_dates), decay computation (on |edge_pp_net|, signed), and data gaps (snapshots written on cache misses). 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 dense but well-organized, front-loading the core purpose. Every sentence adds information. Could benefit from bullet points for return fields, 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?

For a tool with no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their contents. It also covers limitations (60-day TTL, intraday not available), making it complete for agent 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 covers both parameters (days, window) with descriptions. The description adds clarity by repeating defaults and clamp values, and by explaining the effect of each parameter (lookback, snapshot family). This adds marginal value beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from sibling tools like polymarket_edges (current snapshots) and polymarket_arbitrage (arbitrage).

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

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

The description explains when to use the tool (to assess edge age and decay) and includes limitations such as the 60-day TTL and daily close data, guiding appropriate contexts. It does not explicitly mention alternatives but provides sufficient context for decision-making.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral details: 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains that partial basket fills can create unhedged directional risk. No contradiction with annotations.

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

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

The description is long (approx. 280 words) but densely packed with essential information. It front-loads the core purpose and then systematically covers modes, parameters, and return fields. While verbose, every sentence adds value and the structure is logical. A slight trim could improve conciseness.

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

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

Given the tool's complexity (two modes, four parameters, significant risk warnings), the description is exceptionally complete. It explains return fields for both modes, warns about thin books and partial fills, and lists specific output fields including 'forced_directional_risk'. Without an output schema, this fully compensates.

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

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

Schema coverage is 100% but the description adds significant context: clarifies that 'event' and 'market' are mutually required, explains the default side logic for basket mode (auto from partition sum), and interprets size_usd differently for single-market vs basket ('spend on buys, target proceeds on sells' vs 'settlement notional'). This goes well 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes two modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use this tool before acting on their outputs.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear context for when to use. It does not explicitly state when not to use, but the strong positive guidance implies thresholds. It also warns about partial fill risks.

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, non-destructive behavior. The description adds extensive behavioral context: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and explanations of what each field means, including edge cases where spreads are meaningless.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. While it is lengthy, the information is relevant and organized, with minimal redundancy.

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

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

Given no output schema, the description fully covers the response structure, including edge cases like compatibility_warning and temporal_alignment. It explains what the tool returns and when results are meaningful, making it very complete for an agent to use correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the two modes (topic shortcuts vs explicit tickers), listing the 10 pre-mapped topics, and clarifying override behavior. This goes beyond the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by specifying the cross-venue nature and the two modes of operation.

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 the topic shortcuts versus explicit tickers, and warns that most pre-mapped topics return compatibility warnings, indicating when not to expect tradeable spreads. This provides clear usage guidance 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping and pairing with siblings but does not disclose additional behavioral traits beyond that. 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?

Two concise sentences covering purpose, usage, and relationships with siblings. Every sentence is informative and front-loaded. 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?

Given the simple single-parameter, no-output-schema tool, the description fully covers what the tool does, when to use it, and how it relates to sibling tools. No gaps.

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

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

Schema coverage is 100% with clear parameter description. The description's main text echoes the schema's parameter explanation but adds no extra semantic value 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?

Description states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', which is a clear verb+resource pairing. It distinguishes from siblings remember and forget by explicitly naming them and describing their roles.

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 concrete scenarios like 'user's target ticker, an address, prior research notes' and states it's scoped to user identifier. However, it does not explicitly state when NOT to use this tool, though the pairing with remember/forget implies the usage boundaries.

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

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

The description discloses behavioral traits beyond annotations, such as the mark_read side effect ('flag returned events read so the next call only shows newer ones'). Annotations indicate readOnlyHint=true and idempotentHint=true, which may conflict with the mark_read behavior, but the description is transparent about the actual behavior.

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

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

The description is concise, front-loaded with the core purpose, and includes necessary details in a logical order. Every sentence adds value, with no fluff. It is efficient and easy to parse.

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

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

Given the 5 optional parameters, no output schema, and annotations covering safety, the description provides a complete picture: return format, filtering capabilities, mark_read behavior, polling suitability, and an alternative access method. It equips an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining mark_read in detail and providing an example for type ('sec_8k'). Other parameters like since and limit have descriptions that overlap with schema, but the added context for mark_read justifies a higher score.

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: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull), and details the return fields. While not explicitly distinguishing from siblings, the purpose is specific and unambiguous.

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

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

The description provides guidance on when to use ('Pull fired events...'), mentions that 'Polls work fine' indicating suitability for polling, and gives an alternative endpoint for scripts/dashboards. It does not explicitly exclude use cases but offers useful context for appropriate 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 declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral details: parallel fan-out, GDELT>GNews fallback, USPTO soft-failure, and return structure. 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 example queries and well-organized. It conveys all necessary information without excessive verbosity, though could be slightly more concise.

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

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

Given the complexity of multiple sources, fallback logic, and relative date formats, the description is complete. It describes the output structure (changes grouped by source, total_changes count, citation URIs) and provides an alternative tool reference.

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 100% gives baseline 3. The description adds extra meaning: explains 'since' format with examples, notes only 'company' type supported, and clarifies 'value' can be ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company in a time window by fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It differentiates from sibling entity_profile for 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?

Explicitly provides example queries and advises when to use entity_profile instead. It also explains the fallback behavior and parameter formats.

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

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

The description adds behavioral context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already indicate idempotentHint=true, but the description clarifies the storage semantics.

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

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

The description is two sentences but packed with information: purpose, usage, scope, pairing. No wasted words; front-loaded with the main action. Every sentence adds value.

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

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

Given there is no output schema and simple inputs (2 strings), the description fully covers behavior (persistence, scoping) and usage context (pair with recall/forget). It is complete for an agent to understand when and how to use the tool.

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

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

Schema coverage is 100% (both key and value described), so baseline is 3. The description adds examples of key names (subject_property, target_ticker, user_preference) and value types (findings, addresses, preferences), enhancing the schema's generic 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: 'Save data the agent will need to reuse later.' It gives specific examples like 'resolved ticker, target address, user preference, research subject,' which distinguishes it from sibling tools like recall 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?

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and pairs it with recall (to retrieve) and forget (to delete), providing clear guidance on alternatives.

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

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

The description discloses important behavioral traits beyond annotations: it notes the cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit reporting of unresolved identifiers. These details provide operational context not covered by the readOnly/openWorld/idempotent annotations.

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

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

The description is long but information-dense, front-loading user-phrasing examples before explaining supported types. Every sentence adds value, yet the block format could be improved with bullet points for faster scanning. Still, it remains well-organized with clear sections.

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

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

With no output schema, the description must explain return structure, and it does thoroughly: for company, all identifiers, sources, and unresolved handling; for drug, the RxCUI/ingredient/brand and citation. It also covers graceful degradation and reduces manual lookups, making it complete for an agent to use correctly.

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

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

Although the schema covers both parameters, the description greatly enriches meaning. For 'type: company', it details the cross-source identity spine (CIK, ticker, LEI, FIGI) and source labeling; for 'type: drug', it specifies RxCUI, ingredient, brand, and citation. It also clarifies accepted input formats, going far beyond the schema's brief descriptions.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This is specific and distinguishes it from siblings like entity_profile or compare_entities, which operate on existing entity data rather than performing name-to-ID resolution.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This tells the agent exactly when to invoke the tool. However, it does not name alternative tools for cases where an ID is already known, lacking an explicit 'when not to use' comparison.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behavioral details: calls ai_visibility_check internally, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density per entity. 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?

Three sentences with clear structure: purpose, mechanics, use case. No redundant information. Well front-loaded with the core action.

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

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

Without an output schema, the description thoroughly details return format (ranked list with score, confidence, signal density). It also covers parameter roles and typical use case, making it complete for a 4-param 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?

Despite 100% schema coverage, the description adds significant value: explains entities ordering (first is 'subject'), default model, _apiKey optionality, and context purpose. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It includes specific verbs like 'probes' and 'ranks', and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and includes an example question. However, it does not explicitly state when not to use the tool or mention alternatives other than implying single-entity check via sibling name.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds key behavioral context: partial failures degrade gracefully, bundlephobia's first call can take 5-30s, and sources_failed will list timeouts. 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 but well-structured: starts with overview, lists return fields, mentions ecosystem, adds performance note. Dense but not verbose; slightly long 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?

No output schema, so description details all return fields: summary block fields, per-advisory detail, links, alternative versions. Also covers partial failure behavior. For a composite tool with 2 parameters, 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 has 100% coverage with clear descriptions. Description adds context: package accepts scoped names, version defaults to latest, and explains the composite nature. Adds value beyond schema by clarifying defaults and scope.

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 performs a composite check for npm packages, covering license, advisories, version history, and bundle size from two services. It specifies the verb 'fans out across' and differentiates from sibling tools by limiting to NPM ecosystem in v1.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and clarifies NPM scope, directing other ecosystems to deps.dev directly. This provides clear when-to-use 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 confirm readOnly, idempotent, non-destructive. Description adds that results are limited to 200 matches and includes what is returned (coordinates, latest version, timestamps). 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 sentence clearly states purpose, scope, and output. No extraneous words. Front-loaded with the action and resource.

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 search tool with 3 parameters and output schema, the description adequately covers purpose, search fields, result limit, and output fields. Lacks pagination details but schema covers start and rows.

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 each parameter described (query, rows, start). Description does not add significant new meaning beyond schema, but provides context that search is on Maven Central packages.

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 'Full-text search across Maven Central packages' with specific fields (groupId, artifactId, version, tags) and output details (coordinates, latest version, download timestamps, up to 200 matches). This distinguishes it from siblings like search_by_coords and search_within.

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 implies general search usage but does not explicitly state when to prefer it over alternatives like search_by_coords or search_within. No exclusions or when-not-to-use guidance provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds 'Structured lookup' but does not disclose additional behavioral traits like pagination behavior, response format, or rate limits. With annotations providing baseline safety info, a 3 is appropriate.

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, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and usage pattern.

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

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

Given that the tool is straightforward with an output schema and full parameter documentation, the description is sufficiently complete. It covers the essential lookup behavior without needing to explain return values, which the output schema handles.

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 parameters are already documented. The description adds value by emphasizing 'any combination', which clarifies that parameters are optional and can be used flexibly. This goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states 'Structured lookup by Maven coordinates' with specific parameters (groupId, artifactId, version). This verb+resource combination is distinct from sibling tools like 'search' and 'search_within', which likely handle free-text or other queries.

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

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

The description implies usage for Maven coordinate lookups and states 'Provide any combination', indicating flexibility. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance. The context is clear enough for an AI agent to infer the use case.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: underlying model (BGE-base-en), chunking (500-char overlapping windows), limit (200K chars truncated and flagged), and return fields (character offsets, similarity scores). 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 concise: two sentences plus a technical note. It is front-loaded with purpose and usage, and every sentence earns its place without redundancy.

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

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

Despite no output schema, the description explains return format (passages with offsets and similarity scores) and behavior for oversized inputs (truncation flagged). This is complete for a search 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 description coverage is 100% with each parameter described. The description adds examples for 'query', clarifies the cap for 'text', and mentions default for 'limit'. This adds value beyond the schema, though schema is already good.

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 does semantic search inside a fetched record. It uses specific verbs and resources, and distinguishes from siblings like 'search' and 'ask_pipeworx_grounded' by emphasizing internal search over a provided text.

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: 'Use when the record is too big to cram into the prompt.' Also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded.' This helps the agent choose wisely.

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 substantial behavioral context beyond the annotations: it notes the tool requires authentication, returns a new subscription ID, details delivery channel constraints (SMS cap, webhook auto-disabling, signing), and explicitly lists supported types with examples. Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description does not contradict 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 front-loaded with the core purpose, followed by requirements, types, and delivery details in a logical order. Every sentence provides unique information without redundancy. It is appropriately sized given the complexity of the tool.

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

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

Given the tool's complexity (multiple subscription types, delivery options, authentication needs), the description covers all essential aspects: return value, required credentials, per-type parameters, delivery constraints, and references to sibling tools. No output schema exists, so the description adequately explains what the tool returns and how it behaves.

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

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

The input schema has 100% coverage, but the description enriches parameters with concrete examples (e.g., items:["5.02"] for sec_8k), detailed format for each subscription type, and additional constraints for delivery channels (SMS verification, webhook HMAC signing). This adds significant value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions (list), unsubscribe (remove), and recent_alerts (view).

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

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

The description explains when to use the tool (proactive monitoring), specifies requirements (Pipeworx OAuth account), and provides context for when not to use it by referencing alternatives like recent_alerts for pulling the feed. It also outlines supported subscription types and delivery channels.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it is an onboarding entry point that returns example questions and can be filtered by topic. 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 moderately long but well-structured. It front-loads alternative phrasing and then gives a clear breakdown of what the tool returns, how to call it, and when to use it. Every sentence adds value, though minor trimming could improve conciseness.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully self-contained. It explains the return format, usage with and without arguments, and the use case. No gaps remain.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaningful detail by listing possible topic values (e.g., finance, pharma) and explaining that omitting the parameter yields a cross-category spread, which enriches the parameter's semantics.

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 returns 'category-bucketed example questions' with 'exact tool + argument shape', and positions itself as an onboarding entry point. This clearly distinguishes it from siblings like 'ask_pipeworx' (which answers questions) or 'discover_tools'.

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

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

The description says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to use it with or without the 'topic' argument. While it lacks explicit 'when not to use', the guidance is clear and actionable.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: deactivation (not deletion) and preservation of historical events via recent_alerts. No contradiction.

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

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

Two sentences, no wasted words. Front-loaded with action and purpose.

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

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

For a single-parameter tool with no output schema, the description fully covers purpose, behavior, side effects, and historical data availability. Paired with annotations, it is complete.

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

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

Schema coverage is 100% and parameter 'id' is well-described as 'Subscription id (uuid) returned by subscribe'. The description reinforces this but adds no new meaning beyond what schema provides.

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

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

The description uses a specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from siblings like 'subscribe' (create) and 'list_subscriptions'. It also adds ownership 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?

States ownership enforcement, so agents know only own subscriptions can be cancelled. Implicitly tells when not to use (for others' subscriptions). Does not explicitly name alternatives but mentions 'recent_alerts' for historical events.

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 declare read-only and idempotent, but the description adds vital behavioral context: the exact verdict taxonomy, the nuanced meaning of could_not_verify (check did not happen, not evidence), the unsupported meaning, and the two-tier processing path. This goes far beyond what annotations provide.

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

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

The description is detailed but every sentence earns its place: trigger phrases, routing logic, return contract, and caveats. It is front-loaded with the core purpose and ends with operational warnings. There is no redundant 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?

With no output schema, the description fully documents the return value (verdict enum, actual value with citation, reasoning) and explains edge cases like could_not_verify and unsupported. Given the tool's complexity (routing, tolerance, error handling), the description is remarkably 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% for both parameters, but the description enriches them: it gives realistic examples for claim, and for tolerance_pct it explains the default behavior, the override mechanism, and recommends 1–2 for hallucination detection. This adds meaning beyond the schema's bare field descriptions.

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

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

The description explicitly defines the tool as 'natural-language claim verification against authoritative sources' and provides clear trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools like search or deep_research by focusing on adjudicating truth, not just retrieving information.

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 clearly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company-financial vs. other claims. However, it does not explicitly mention alternate tools or when NOT to use it, so it falls short of a 5.

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