Codestats

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond annotations: it explains the default model (Workers AI Llama-3.3-70b), billing implications of passing _apiKey, and the exact return structure (score, confidence, signals, raw_response). No contradiction exists between annotations and description.

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

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

The description is four sentences, each serving a distinct purpose: purpose, default/API key, return format, and use cases. It is front-loaded with the core function and contains no fluff or repetition. Every sentence earns its place.

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

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

With no output schema, the description compensates by laying out the per-model return fields and the combined view. It covers model selection, auth/billing, and examples of use. A minor gap is lack of error/edge-case behavior (e.g., rate limits or unexpected responses), but overall it is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning to parameters, particularly _apiKey (BYO key, direct payment) and models (default is workers-ai, anthropic optional). It also clarifies that entity/context are used for the probe, reinforcing schema descriptions without redundancy.

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: probing one or more LLMs and scoring visibility (0-100) per model. It distinguishes itself from sibling tools by focusing on multi-model visibility scoring rather than simple Q&A or research. The phrase 'Probe one or more LLMs' is a specific verb+resource that leaves no ambiguity.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also provides context on when to provide an optional Anthropic API key (to include Anthropic, with direct billing). However, it does not mention when not to use the tool or name specific alternative tools, so it lacks explicit 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, shielding safety concerns. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also notes it is a fast default entry point and works across tiers, providing a clear picture of behavior beyond static annotations.

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

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

The description is front-loaded with the most important instruction and includes examples and escalation paths. It is slightly long (about 150 words) and could trim minor redundancies like 'works on every tier', but every sentence earns its place for a default tool with broad scope.

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

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

The description is thorough for a tool of this complexity: it covers domain coverage, example queries, output format with citations, and when to escalate to alternatives. No output schema exists, but the description explicitly describes the return type (structured answer with pipeworx:// citation URIs), making it complete.

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

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

The input schema has 100% coverage, with six parameters all clearly described as aliases for 'question'. The description provides concrete example questions but does not add new parameter-specific semantics beyond what the schema already states. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it answers questions about real-world data by routing to a large set of verified tools. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, and specifies the resource (current/historical data across many domains).

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with clear conditions for when to use alternatives ('Step up only when needed' and names ask_pipeworx_grounded and deep_research). It also lists example queries and covers when to avoid using it for broad/multi-part questions.

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, open-world, idempotent, and non-destructive. The description adds value by disclosing the experimental nature of routing improvements and how results are compared against the stable router. It also clarifies there is no fallback—it is a full working router—providing context beyond the annotations.

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

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

The description is concise yet comprehensive. Each sentence adds value: defines the beta nature, states current equivalence, gives usage guidance, and clarifies fallback. It is front-loaded with the key identity of the tool and avoids redundancy.

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

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

The description covers the tool's experimental status, current behavior (no active candidate), usage instructions, and response shape consistency with ask_pipeworx. While there is no output schema, the mention of 'same response shape' provides sufficient context. It could elaborate on what happens when a candidate becomes active, but that is not essential for immediate 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 description coverage is 100%—all six parameters are documented as aliases for 'question'. The description mentions 'same arguments' as ask_pipeworx but does not add new information about parameter syntax or formats beyond what the schema already provides. It meets the baseline for well-documented schemas.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by being the experimental edge, making the 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 gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that no candidate is active currently, so it matches ask_pipeworx exactly, implying both are interchangeable at present. However, it does not explicitly state when NOT to use it or mention other sibling alternatives beyond ask_pipeworx.

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?

Despite strong annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral detail: exact return structure on success, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the guarantee of using only tool result content. This goes well beyond the annotations and fully discloses edge cases and failure modes.

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 longer than average but every sentence contributes functional value: purpose, routing, mechanism, output/refusal format, use cases, and cost trade-off. It is front-loaded with the most important info and does not waste words, though it could be slightly more concise by trimming redundant phrasing like 'Same routing as ask_pipeworx' (already implied).

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 (an LLM-based grounded answer tool) and lack of an output schema, the description is exceptionally complete. It explains the full success and refusal contract, the cost implication, and when to prefer the alternative. The agent has all necessary context 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 the 'question' parameter and several aliases clearly documented. The description does not add any additional parameter meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema fully handles parameter documentation.

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

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

Description opens with 'Hallucination-resistant answer mode for high-stakes reads' which clearly identifies the purpose and distinguishing feature. It specifies it routes like ask_pipeworx but extracts answers only from tool results, distinguishing it from the sibling tool and other lookup 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and lists example domains. Also provides a clear exclusion/alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, giving practical guidance on choosing between the two 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description goes far beyond that. It discloses blocking status routes, low-confidence short-circuit behavior, suppression of analysis fields, status codes ('low_confidence_match', 'market_closed_or_inactive'), wide-spread tradeability, and resolution-rule risk with examples. This is rich behavioral context that annotations alone could 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?

The description is long, but every section earns its place given the tool's complexity and the absence of an output schema. It is well-structured with uppercase section markers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose and usage. It could be trimmed slightly, but it is appropriately sized for the tool's richness.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively. It details result shapes (market, analysis, evidence), the resolver contract (market_match_confidence, score, alternatives, suggestions), parent event extraction, news fallback fields, safety statuses, and cancellation-rule risk. This is complete enough for 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?

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description repeats the market input formats (slug, URL, question text) already present in the schema, and it does not add new parameter-specific semantics for depth or include_raw. It offers examples and fan-out details, but these are behavioral rather than parameter-semantic contributions.

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 and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by focusing on bet research with resolution, classification, and a market-vs-model comparison. The explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further clarify its purpose.

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

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

The description gives explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also clarifies input forms and fan-out behavior. However, it does not explicitly state when NOT to use this tool in favor of an alternative sibling, so it stops short of a 5.

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

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

Even though annotations already mark it as read-only and idempotent, the description goes beyond by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, metric-specific outputs, sorting behavior, and the return format (paired data + pipeworx:// citation URIs). This adds significant behavioral transparency.

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 trigger phrases and clear structure, but includes some redundancy (e.g., 'ALWAYS PREFER' and 'Replaces 8–15 sequential lookups'). It is slightly verbose but every section earns its place in conveying the tool's behavior 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?

For a two-parameter tool with no output schema, the description is unusually complete: it covers input expectations, data sources, edge cases (off-calendar fiscal years), output format, and result ordering. There is no additional needed context for an agent 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?

The input schema already documents both parameters and the enum for type, but the description adds domain-specific meaning: type='company' pulls specific 10-K metrics, type='drug' pulls FAERS/FDA/trial counts, and values are exemplified with tickers/names. This enriches the schema's basic descriptions.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes trigger examples ('X vs Y', 'which is bigger') and explicitly distinguishes itself from sequential single-pack lookups, making it differentiable from sibling tools like entity_profile.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also specifies what types of comparisons are supported (companies/drugs) and gives concrete examples, clearly framing when this tool should be chosen over the alternative approach.

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 numerous behavioral traits beyond the annotations: decomposition into facets, parallel routing to 5,529 tools, findings packet with verbatim evidence + confidence + source + citation, explicit gaps[] for unanswered facets, contradictions[] flags, semantic excerpting, hop fields, and latency expectations. It clarifies that findings are never invented and citations are always fetchable. No contradiction with annotations exists.

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 densely packed, starting with critical prerequisites (account requirement), then core functionality, depth semantics, and finally output details. Every sentence adds distinct value, though the length is near the upper limit; it is structured effectively 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?

Given no output schema, the description fully covers the return format (findings packet with citations, gaps, contradictions), limitations (not for current news), depth options with behavioral differences, and performance expectations. The agent has enough detail to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning to the 'depth' parameter by explaining what each level does ('standard re-angles unanswered gaps... thorough additionally chases the best leads') and clarifies that broad/multi-part questions are intended. This elevates it beyond what the schema alone 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' and immediately differentiates from siblings by noting it is 'NOT open-web search' and contrasting with ask_pipeworx for single lookups. This clearly distinguishes the tool from the many sibling 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 usage guidance with alternatives: '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'. It also states the tool is 'Best for broad/multi-part questions over structured data', giving clear when-to-use criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral detail beyond annotations: it returns top-N relevant tools with full schemas and examples, and that results are ready to call directly without a second schema lookup. This enriches the agent's understanding of the tool's 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 appropriately sized and front-loaded with the core purpose. It covers usage context, return format, and a strategic directive in two sentences without redundancy or filler. Every clause 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 no output schema, the description explicitly explains what the tool returns (top-N tools with names, descriptions, schemas, curated examples) and that they are directly callable. Annotations cover safety traits. For a discovery tool of moderate complexity, the description is complete and leaves no critical gaps for 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 description coverage is 100%, so the schema documents query, limit, and aliases thoroughly. The description adds minimal extra meaning (e.g., 'describing the data or task' and 'top-N'), but these are already implied by the schema descriptions. It does not significantly compensate beyond the schema baseline.

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

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

The description uses a specific verb phrase ('Find tools by describing the data or task') and clearly identifies the resource (tools). It differentiates this tool from siblings by positioning it as a discovery/search mechanism rather than a domain-specific query tool, exactly what an agent needs to select it.

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 explicit use cases ('Use when you need to browse, search, look up, or discover what tools exist') and provides a strong directive ('Call this FIRST when you have many tools available...'). This gives clear when-to-use guidance, particularly valuable given the large sibling list.

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

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

Beyond read-only/idempotent annotations, it discloses the fan-out across specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), the exact return fields, and a special caveat about USPTO PatentsView API sunset with soft-fail behavior. This adds meaningful behavioral context not available from annotations alone.

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

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

The description is long but information-dense, with example queries front-loaded and critical details (return fields, caveats, parameter constraints) packed in. It could be more structured, but every clause carries useful guidance.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik/company_name, recent_filings with URIs, fundamentals fields, patents, news, and LEI. It also covers inputs and edge cases completely.

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 both parameters are already well-described. The description reinforces the same semantics with examples (ticker 'AAPL', zero-padded CIK) but adds no genuinely new meaning beyond the schema.

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

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

The description clearly states a specific verb+resource: full cross-source profile of a US public company in one parallel call. It distinctively positions itself against sibling tools by explicitly naming alternatives like resolve_entity for names and single-pack SEC/XBRL/news lookups.

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

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

Provides explicit when-to-use examples ('Tell me about X', 'research Acme') and explicit when-not-to-use guidance: names not supported, use resolve_entity first. It also instructs to ALWAYS PREFER this over chaining single-domain lookups for holistic views.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat safety. It adds behavioral context by explaining the purpose for deletion (stale context, task done, sensitive data) and the relationship with sibling tools, which goes beyond the annotations.

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

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

The description is two sentences: the first states the core action, the second provides usage guidance and sibling relationships. Every sentence earns its place, with no wasted words, and it is front-loaded with the primary 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 simple single-parameter delete tool with strong annotations (destructive and idempotent hints) and clear usage guidance, the description is complete. It covers what, when, and how it relates to other tools; no output schema exists, so return values need not be explained.

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% (the only parameter 'key' is described as 'Memory key to delete'), so the schema carries full parameter documentation. The description simply says 'by key' without adding new detail, so baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes itself from siblings like remember and recall by explicitly pairing with them for complementary 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?

The description explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, providing clear context relative to 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, idempotentHint, and non-destructive, but the description adds meaningful behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond the annotations without contradicting them, though it doesn't address potential errors or rate limits.

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

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

The description is concise and well-structured: it starts with the primary action, then explains the process and output format, and ends with practical use cases. Every sentence earns its place with no redundancy or filler.

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 two-parameter read-only tool without an output schema, the description sufficiently covers the return value ('a single text blob ready to drop at site-root/llms.txt') and typical use. It doesn't describe edge cases or limitations, but these aren't necessary for such a straightforward 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% and both parameters (url, max_links) are self-explanatory in the schema. The description adds no additional parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file'), and clarifies scope ('for any URL'). It explains the process (fetches, extracts, emits) and differentiates from siblings by focusing on a distinct output artifact, making it clear what the tool does.

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

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

The description lists concrete use cases ('getting a client's site indexed by AI', 'drafting llms.txt', 'auditing how an AI crawler would see a competitor'), providing clear context for when to use it. However, it doesn't explicitly name alternative tools or state when not to use it, stopping short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds useful context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the caller-scoped nature ('caller's active subscriptions'). No contradiction.

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

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

The description is two sentences, front-loaded with the primary purpose, and efficiently combines return value details with usage guidance. No wasted words.

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

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

For a simple read-only list tool with a single optional parameter, the description covers purpose, return fields, and usage context. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The only parameter, include_inactive, is fully described in the schema with 100% coverage. The description does not add extra meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List the caller's active subscriptions.' It enumerates return fields and distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on read-only listing.

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

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

The description provides explicit usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly references subscribe and unsubscribe as alternatives, though it doesn't name them or provide 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 only set negative hints (readOnlyHint=false, etc.), while the description adds substantive behavior: filing without an account returns a claim_token, the token can be reused later to check resolution, feedback is rate-limited to 5 per identifier per day, and it is free/counts no quota. This goes well beyond the annotations and 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 dense and long, but every clause carries useful guidance: use cases, exclusions, token flow, rate limits, and relevance. It is front-loaded with the core purpose. Slightly unfocused as a single wall of text, but no sentence is wasted.

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

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

Given no output schema, the description fully explains expected return behavior (a claim_token on first filing, status/resolution when reused). It also covers prerequisites (account optional), daily limits, and how the feedback is processed (daily digest, roadmap impact), making the tool's behavior comprehensive for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: it clarifies the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})... with no other arguments'), advises against pasting end-user prompts, and emphasizes being specific in the message. This enriches parameter understanding 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and overall scope (Pipeworx tools), distinguishing it from sibling tools like ask_pipeworx 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?

Explicit usage criteria are given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion and alternative: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it is a 'self-aggregating signal — derived from CF analytics-engine, no PII', and 'cached 5min-1h depending on window'. This explains the data provenance, privacy characteristics, and freshness behavior, which are not covered by annotations.

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

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

The description is concise and well-structured: a one-sentence purpose, a 'Useful for' list with three bullet points, and a closing note on aggregation and caching. Each sentence serves a distinct function, no filler, and the most essential information is front-loaded.

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

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

There is no output schema, so the description partially compensates by stating it returns 'top tools, top packs, and total call volume' and clarifying the data shape as 'just (pack, tool, count)'. It also notes caching behavior. For a simple one-parameter tool, this is fairly complete, though the exact return format (e.g., field names, structure) is not fully specified.

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 only parameter ('window') is fully documented in the schema with an enum and description explaining the trade-off between shorter and longer windows. The description merely repeats the window values without adding nuance. Schema coverage is 100%, so the description adds little for parameter semantics, meeting the baseline of 3.

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

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

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This clearly identifies the verb (returns), the resource (trending call data), and distinguishes it from siblings like discover_tools or recent by focusing on aggregated AI-agent call patterns.

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 'Useful for' list provides three explicit use cases: discovering hot data sources, confirming a canonical tool, and aligning use cases with agent needs. This offers clear context for when to use the tool. It does not explicitly name alternatives, so it misses the 'when-not/alternatives' element, but the context is strong.

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

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

Annotations already declare read-only/idempotent/open-world, but the description goes far beyond by explaining internal thresholds (3pp, 0.30 Jaccard), partition filters (placeholder slugs), the fill check against live CLOB depth, and the caution 'realizable_edge_pp ≤ 0 ... do not trade it.' This provides actionable behavioral context without contradicting the annotations.

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

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

Although long, every sentence contributes. The description is front-loaded with the core purpose and uses bolded section headers (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) to organize dense information. No redundancy or filler.

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

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

Despite no output schema, the description specifies the response structure (opportunities[], partition_check fields, skipped_low_similarity, thin_legs[]). It covers edge cases, thresholds, fill-check semantics, and custom sizing—making it fully self-sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, but the tool description adds significant meaning: it details what happens when each parameter is passed, gives example values ('fed-decision-may-2026'), and explains the difference between event and topic modes. This is far beyond the schema's one-line descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes its three modes (trending_scan, event, topic) and even references a sibling tool (polymarket_fill_risk) for custom sizing, setting it apart from other Polymarket 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?

Usage is explicitly laid out: 'Call with NO args for a trending_scan... pass `event`... or `topic`.' It provides concrete examples for each mode, explains when to prefer event vs topic, and points to an alternative (polymarket_fill_risk) for custom sizing. This is model-tier 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?

Despite having annotations that already declare safe read-only and idempotent usage, the description adds substantial behavioral context: caching at the KV level, response structure with segment grouping, diagnostics for empty segments, 24h move warnings, and how knobs filter opportunities. 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 long and dense, but it is well-structured with clear sections (purpose, model families, knobs, response structure, caching) and front-loaded with the key use case. Some details like specific alpha values are more than needed for invocation but do add behavioral transparency. Overall, it is appropriately detailed for a complex tool, though slightly verbose.

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 optional parameters, no output schema), the description comprehensively covers output structure, response segments, field semantics, diagnostics, and the reasons segments might be empty. It explains caching and edge conditions, making it complete for an agent to understand what to expect and why.

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

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

The schema already provides 100% parameter descriptions, but the tool description goes further by explaining the purpose of tradeable-edge knobs, the special interaction of min_kelly vs min_partition_leg_kelly (partition arbs bypass min_kelly), and how min_liquidity/max_spread_pp affect realizability. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case for daily betting discovery. It does not explicitly reference sibling tools but the purpose is distinct and specific.

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

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

The description gives clear context: built for 'what should I bet on today' and for agents to discover opportunities without paging through hundreds of markets. It does not mention when to use alternative tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state 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 declare it read-only and idempotent, and the description adds substantial behavioral detail beyond that: data is built from daily snapshots, bounded by a 60-day TTL, starts when snapshotting was enabled, uses daily closes net of default slippage, and snapshot gaps mean no scan occurred. No contradiction with annotations.

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

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

Though long, the description is densely packed and well structured: it front-loads the core purpose, then uses labeled sections (Args, RESPONSE, LIMITS) to convey complex telemetry semantics efficiently. Every sentence adds value, and there is no filler.

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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and their interpretations, plus limitations on history depth and decay computation. This is complete enough for an agent to understand what the tool returns and its constraints.

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?

Input schema already provides full descriptions for both parameters (100% coverage), including defaults and clamps. The description restates the defaults and adds the phrase 'snapshot family' for window, which slightly clarifies intent but does not significantly expand on the schema's 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?

Description clearly states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the concrete question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence and decay rather than current edges.

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

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

The description gives clear context for when to use the tool by framing the use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and defines the response categories. It does not explicitly name alternative tools or state when not to use it, but the implied usage scenario is strong 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?

The description details internal behavior: it walks the order book ladder, computes top-of-book vs VWAP, identifies thin legs and forced directional risk, and explains partial fill consequences. Annotations already declare readOnly/openWorld/idempotent hints, and the description adds depth beyond those 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 long but efficiently structured: a one-line purpose, REQUIRES clause, mode-specific details, and a use-case directive. Every sentence contributes novel information, and the structure (SINGLE-MARKET vs BASKET) makes 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?

With no output schema, the description fully enumerates return fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), covers both modes, parameter interpretation, and the rationale for using the tool. This is complete for a 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?

Although the schema covers all 4 parameters, the description adds crucial interpretation, especially for size_usd (max spend vs target proceeds in single-market, settlement notional in basket) and side (default auto in basket). This enriches the schema meaningfully.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the tool's function. It further distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly referencing them as the tools to precede this one, and details both single-market and basket modes with specific return values.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position. This provides clear when-to-use context and distinct guidance versus alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the exact logic of compatibility_warning, temporal_alignment, and skipped_cross_type/subtype counters. It even quantifies typical spread ranges (2-25pp) and explains why they exist. No contradiction with annotations; the description adds substantial 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?

The description is longer than average but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the purpose in the first sentence and each subsequent paragraph addresses a distinct aspect. Some editorial content about participant pools is arguably optional but adds context for interpreting when the tool is useful; still, it's disciplined overall.

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

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

With no output schema, the description compensates by explaining the response structure (leg prices, top_spreads_pp), the safety fields and their trigger conditions, and temporal alignment semantics. It covers both modes, the tradeability warning, and the skip counters, making it complete for a complex cross-venue tool. The only minor gap is not showing the exact JSON shape of spread[], but the field descriptions suffice.

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

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

The schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds the concept of two modes (topic vs explicit override), clarifies that explicit ticker/slug override the topic-mapped side, and lists the 10 valid topic strings. This enriches the parameter intent 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the resource and the analytical intent. It distinguishes from siblings like polymarket_arbitrage by emphasizing the two-venue comparison. Though it uses a noun phrase rather than an explicit verb, the purpose is 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 explains two modes (topic shortcuts vs explicit ticker/slug) and gives explicit conditions under which the output is meaningless via compatibility_warning. It cautions that 'pre-mapped ≠ tradeable' and most topics return warnings, serving as a when-not-to-use signal. It doesn't name alternative sibling tools explicitly, but the 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context not captured by annotations, such as the scoping to 'anonymous IP, BYO key hash, or account ID' and the dual behavior of retrieving a single key versus listing all keys. 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, each earning its place: the first states the action, the second explains when and why, the third covers scoping and related tools. No filler, front-loaded with the primary purpose, and easily skimmable.

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 two-mode retrieval tool with one optional parameter and no output schema, the description is fully complete. It explains both output modes (value or key list), gives usage context, and states the scoping model, leaving no significant operational gaps 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?

The schema already covers the single optional key parameter at 100%, so the baseline is 3. The description goes beyond the schema by giving concrete examples of what the key might be (target ticker, address, research notes) and reinforces the omit-to-list behavior, adding practical semantic richness.

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 ('Retrieve') and names the resource ('a value previously saved via remember'), and immediately distinguishes the list-all-keys mode. It clearly separates itself from sibling tools like remember and forget while explicitly identifying the memory storage concept, so there is no ambiguity about what the tool does.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier' and gives concrete examples (target ticker, address, research notes). It also names the companion tools ('Pair with remember to save, forget to delete'), establishing clear when-to-use 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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context (time window, breakdown by language/machine, lifetime totals) not captured in annotations, but does not detail response format or edge cases.

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

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

The description is a single sentence that packs in context and value, but the opening fragment 'Code::Stats (codestats.net) —' is slightly clunky. It is concise and mostly front-loaded, with no wasted words.

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

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

Despite 0% schema coverage, the description covers purpose, time window, breakdown dimensions, and lifetime context. The output schema exists, so return value details need not be explained. Missing: no mention of what happens for invalid usernames or whether data updates in real-time, but overall it's sufficiently complete for a simple one-param read-only 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 0%, so the description must compensate. It explains the username as a Code::Stats user but does not specify format, case sensitivity, or behavior for non-existent users. With only one required param and clear context, it barely meets the baseline; schema does minimal work.

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

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

The description clearly states a specific verb ('Answers how much... coded today') with a unique resource ('Code::Stats user') and scope ('roughly the last 12 hours'), while also distinguishing from siblings like recent_changes by focusing on XP earned and language/machine breakdown. It is specific enough to stand alone.

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

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

The description implies when to use it (when you want to know a user's recent coding activity in the last 12 hours), but does not explicitly mention alternatives or exclusions. Sibling tools include recent_changes and user, which could be conflated, yet no comparison is 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?

The description describes a state mutation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the annotation readOnlyHint: true, which asserts the tool does not change state. This is a critical inconsistency that could mislead an agent about side effects.

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

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

The description is compact yet information-dense, with the main purpose front-loaded in the first sentence. Each sentence adds novel value: return payload details, filtering/mark_read semantics, and an alternative data access URL. No filler or redundancy occupies the text.

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

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

The description covers the return payload (source, citation_uri, raw event), filter options, mark_read behavior, polling suitability, and a direct feed URL. It omits details on how limit interacts with unread_only or mark_read, but those are documented in the schema. For a tool with no output schema and five optional parameters, this is nearly 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 already documents all five parameters with 100% coverage, providing a baseline of 3. The description adds meaningful context beyond the schema: it gives a concrete example for type ('sec_8k'), explains the consequence of mark_read (future calls show only newer events), and mentions the combination of type and since filters. This enhances the agent's ability to use parameters 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It further clarifies what is returned (source, citation_uri, raw event payload) and distinguishes itself from generic recent-activity tools by focusing on the evaluator-written persisted feed. This clearly establishes the tool's unique scope among siblings like 'recent' and 'recent_changes'.

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

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

The description gives clear usage context: polling works fine, an alternative HTTP endpoint is provided for scripts/dashboards, and mark_read controls forward progress. It doesn't explicitly contrast with sibling tools or state when not to use, but the integration guidance and mark_read sequencing offer strong practical direction.

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 well beyond annotations: fans out in a parallel call, uses fallback order (GDELT→GNews), and notes the USPTO/PatentsView soft-fail after May 2025. It also states the output shape (changes[], total_changes, citation URIs). This is rich transparency and does not contradict 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 dense but well-organized: it opens with user-intent examples, states the core parallel-feed behavior, explains source-specific fallbacks, documents input formats, summarizes output, and closes with an alternative. Every sentence earns its place and there is no filler or redundancy.

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

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

Given the tool has no output schema, the description fully compensates by listing the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). It also covers all three parameters, source behavior, time-window formats, fallbacks, and the main alternative. This is complete for a 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 the baseline is 3. The description repeats the schema's `since` semantics (ISO or relative shorthand) and the `value` examples (ticker or CIK), but adds no new meaning beyond what the input schema already documents. It does include a typical-monitoring suggestion ('30d' or '1m'), but that is also present in the schema's `since` 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 identifies this as a change-feed tool for a company over a date window, with concrete natural-language examples ('What's new with X', 'updates on Acme'). It distinguishes itself by naming entity_profile as the alternative for static profiles, and the fan-out to SEC, GDELT/GNews, and USPTO makes the scope unmistakable.

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

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

The description gives explicit when-to-use guidance via query patterns and an explicit alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This is a clear when/alternative distinction, and it explains the fallback behavior (GDELT preferred, GNews on rate-limit/5xx), which helps with trust.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds critical behavior beyond annotations: 'scoped by your identifier,' persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. It also notes the key-value storage format. No contradiction with annotations; description enriches the agent's understanding of side effects.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by usage context, and ends with storage semantics and sibling references. Every sentence adds value with no redundancy or filler.

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 (2 parameters, no output schema), and the description covers purpose, when to use, persistence behavior, and related tools. This is fully sufficient for an agent to select and invoke the tool correctly with no missing critical information.

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

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

Schema description coverage is 100%, with clear explanations for both 'key' (e.g., 'subject_property') and 'value' (any text). The description reinforces key-value pairing but does not add new parameter-specific details beyond what the schema already provides. Hence, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with a specific verb and resource (key-value store). It further differentiates from siblings by explicitly naming recall (retrieve) and forget (delete), making its role in the memory system unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with examples like resolved ticker or user preference. It also clarifies the alternative path by instructing to pair with recall for retrieval and forget for deletion, effectively distinguishing from 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?

The description adds substantial behavioral context beyond the annotations: it explains multi-source enrichment, graceful degradation, explicit `unresolved` handling, and the cascading internal lookups. This is exactly the kind of context that helps the agent set expectations.

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 longer than average but well structured: it starts with illustrative user queries, then provides a crisp one-sentence purpose, followed by detailed type-specific behavior. The length is justified by the information density; no sentence is filler.

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

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

With no output schema, the description carries the burden of explaining return behavior. It does so thoroughly: list of identifiers per type, source labelling, unresolved field, degradation semantics, and even a citation scheme. This is complete for a lookup tool.

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

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

Schema coverage is 100%, but the description enriches the parameters by giving concrete examples (e.g., AAPL, 0000320193) and clarifying what each type resolves to. It also explains the meaning of 'company' vs 'drug' beyond the enum labels, adding real 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 resolves names to canonical/official identifiers and explicitly distinguishes its role as the 'FIRST' step when an ID is needed. It lists concrete examples of verbs and resources (ticker, CIK, LEI, RxCUI), making the purpose unmistakable.

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

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

It provides an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' This clearly states when to use the tool. However, it does not explicitly state when not to use it or name alternatives, 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.

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context by stating it probes each entity with ai_visibility_check and ranks results, which goes beyond annotations without contradicting them. It does not mention external API calls or auth details, but that is partially in the schema.

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

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

Three sentences, front-loaded with the main action, includes a useful example, and specifies return fields. Every sentence earns its place with no redundant information or padding.

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

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

Given the moderate complexity and the rich annotations + full schema coverage, the description adequately covers purpose, process, use case, and output. It clearly states the tool calls ai_visibility_check and returns a ranked list with score/confidence/signal density, so an agent can invoke 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 detailed descriptions for all parameters. The description adds minimal extra meaning beyond the schema, such as reinforcing that entities are brand names and first is the subject, but this is already present in the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity ai_visibility_check sibling. It also describes the ranking process and return fields, leaving no ambiguity about what the tool does.

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

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

It explicitly frames the tool for competitive AI-marketing audits and gives an illustrative example ('does Claude know about us as well as our competitors?'). However, it does not explicitly contrast with single-entity alternatives or list specific conditions 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.

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral details: fan-out across external APIs, exact return fields, partial failure degradation, and a 5-30s latency for bundlephobia's first measurement with 'sources_failed' listing timeouts. This fully prepares the agent for realistic behavior and edge cases.

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

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

The description is a dense paragraph but every sentence contributes: purpose, use cases, return summary, ecosystem limitation, and failure modes. It could be slightly more structured (e.g., bullet points), but it remains readable and front-loaded with the key purpose. Appropriate for a composite 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 (external API fan-out, no output schema), the description is remarkably complete. It lists the exact summary fields, behavior on partial failures, latency expectations, and alternative routing for non-npm ecosystems. An agent has enough context to invoke it correctly and interpret results confidently.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context around the 'version' parameter (defaults to latest, returns alternatives) and clarifies the package scope, but most parameter semantics are already captured in the schema's field descriptions. No significant addition beyond what's structured.

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: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly distinguishes itself from siblings by naming the exact external sources (deps.dev, bundlephobia) and the scope (npm ecosystem only). This leaves no ambiguity about the tool's 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 is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', correctly directing non-npm queries to an 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds non-obvious behavior: BGE-base-en embeddings, cosine over 500-char windows, and a 200K char truncation cap with flagging. 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?

Three dense sentences, each serving a distinct purpose: defining the tool, giving usage guidance, and revealing technical implementation. Front-loaded with the core semantic action; no filler words.

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

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

The description covers purpose, usage, algorithmic details, input requirements, and return format (passages with offsets and similarity scores). Combined with annotations and schema, the agent has all necessary context to invoke the tool correctly, even without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real-world meaning beyond field labels: text is 'a fetched record' (SEC 10-K, article, tool result) and query examples ('supply-chain risk', 'drug interactions with warfarin') help agents formulate appropriate natural-language queries. This extra context justifies a 4.

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

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

The description clearly states a specific action: 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K body, article). It distinguishes from siblings by emphasizing it operates on already-pulled text and by pairing with ask_pipeworx_grounded for downstream grounding.

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' and describes the workflow with ask_pipeworx_grounded as an alternative to grounding over the whole document, providing clear context and a naming 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?

Beyond the annotations, the description details behavioral specifics: OAuth account requirement, SMS verification and 10/day cap, webhook signing secret returned once, auto-disable after 10 consecutive failing runs, and the always-on feed. This is exactly the kind of context that helps an agent understand side effects and constraints.

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: it front-loads the core action, then covers supported types and delivery channels. Each sentence delivers actionable information without fluff, making the length appropriate for the tool's complexity.

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

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

With no output schema, the description still covers the return value (new subscription ID), the always-on feed retrieval method, all type parameters, delivery channels, and critical caveats like webhook signing and auto-disabling. It is complete enough for an agent to decide whether and how to call 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?

Although schema coverage is 100%, the description adds concrete examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id) and explains the delivery object's fields and constraints. This goes well beyond the schema's terse 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 opens with 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the new subscription ID. This clearly defines the action and outcome, and it is easily distinguishable from sibling tools like list_subscriptions and recent_alerts.

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 the key prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and explains delivery channel options. However, it does not explicitly mention when not to use this tool or directly contrast it with alternatives, so it stops short of a full 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: it returns results 'drawn from the live catalog of thousands of tools' (implying dynamic content) and provides the exact tool + argument shape for each suggestion, which is a key behavioral trait.

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 longer than typical, but it front-loads the purpose with a list of natural-language queries and packs every sentence with useful content (output structure, live catalog, usage, and relationship to meta-tools). It is well-structured with a list of categories and explicit guidance, earning a 4 despite its length.

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

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

Given there is no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool + argument shape), how to call it (no args or topic), and when to use it (first contact and learning meta-tools). It covers the tool's role, parameters, and return behavior comprehensively, making it complete for a discovery tool.

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

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

The schema already documents the 'topic' parameter completely (enum-like list of valid values and the behavior when omitted). The description adds minimal extra meaning beyond the schema, only giving a few examples ('finance', 'pharma', 'betting') and saying it focuses the results. This aligns with the baseline 3 for full 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 identifies the tool as the onboarding entry point for agents wanting to know what Pipeworx can do, explicitly listing example queries and the output (category-bucketed example questions with exact tool and argument shape). It distinguishes from siblings by positioning it as the 'FIRST' step before using meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

The description gives an explicit directive: '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 specifies argument usage ('Call with no arguments for the full spread, or pass topic') and names the meta-tools it teaches, clarifying when not to use it (i.e., when you already know what to ask or need direct data).

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive nature ('row is deactivated, not deleted') with a reference to data retention via 'recent_alerts'. This aligns with destructiveHint=false and enriches the agent's understanding.

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 tightly written with three sentences, each providing essential information: the action, the ownership rule, and the side-effect behavior. No wasted words or redundancy.

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

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

For a simple one-parameter mutation tool with comprehensive annotations, the description fully covers the purpose, the key constraint, and the effect on data. No output schema is present, but the description explains what happens (deactivation) sufficiently for an agent to select and invoke the tool.

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

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

The input schema already documents the 'id' parameter clearly (100% coverage), but the description adds the crucial constraint that the id must belong to the caller ('your own subscriptions'). This goes beyond the schema and helps the agent validate the parameter's usage.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. The purpose is unambiguous and directly tied to the tool's name.

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

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

The description clearly implies when to use the tool (to cancel a subscription) but does not explicitly mention alternatives or exclusions. Context is clear but lacks an explicit contrast with sibling tools such as 'subscribe' or 'list_subscriptions'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety semantics are covered. The description adds meaningful context: the profile is 'public' and the exact XP fields returned. This goes beyond the structured annotations.

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

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

The description is a single, efficient line with no redundant words. However, it is a fragment and could benefit from a verb to clarify the action. It is appropriately sized but slightly under-specified.

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

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

The tool is simple (one parameter) and has an output schema, so return format is already covered. The description conveys the core data content, but lacks usage guidance and any connection to the input parameter, making it only partially 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 schema has one required 'username' parameter with no description, and schema description coverage is 0%. The description does not mention the parameter or explain how the username is used, leaving the agent to rely on the parameter name 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 identifies the tool as returning a public profile with XP breakdowns (total, per-language, per-machine). Although it lacks an explicit verb, the intent is evident. It differentiates from siblings like entity_profile by focusing on user-specific XP data, though it does not explicitly contrast with them.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only states what the profile contains, without mentioning scenarios, prerequisites, or exclusions. There is no 'use this when' or 'instead of' 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 read-only, open-world, idempotent, and non-destructive hints. The description adds crucial behavioral semantics: 'could_not_verify' means the check did not happen and carries a verification_error (not evidence for/against), while 'unsupported' means no source covers it. It also explains grounding, verbatim evidence, and judging behavior beyond the annotations.

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

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

The description is long but every sentence earns its place: query examples, routing logic, return verdicts, citation format, error semantics, and the efficiency benefit over sequential calls. It is front-loaded with the key use case and contains no filler or repetition of schema fields.

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

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

With no output schema, the description compensates by enumerating the full set of verdicts, describing the returned value and citation, and clearly distinguishing 'could_not_verify' from 'unsupported'. It covers behavior for both company-financial and general claims, including failure modes, making it complete for a 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 covers both parameters at 100%, so baseline is 3. The description adds value by explaining tolerance_pct operational semantics: it overrides the tolerance implied by the claim wording, suggests 1–2 for hallucination detection, and notes the default is capped at 5. This goes beyond the schema's basic range 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 opens with concrete natural-language phrasings and explicitly names the tool's function as claim verification against authoritative sources. It clearly distinguishes this from sibling tools by focusing on fact-checking a user's claim and by describing a specific dual routing path for financial vs. other factual claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines when the SEC EDGAR/XBRL fast path applies versus the grounded pipeline. It does not name sibling alternatives or state exclusions, but the context is strong enough to guide tool selection.

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