Maven Central

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

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

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

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

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

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

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

Despite lacking an output schema, the description explicitly states the return structure (per-model object with score, confidence, signals, raw_response plus combined view). All four parameters are described in the schema, and the description adds enough context for correct invocation. The tool's moderate complexity is fully covered.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds semantic value by clarifying the default model, explaining the optional _apiKey purpose, and providing example values for 'entity' and 'context'. This provides a baseline of 3, and the extra usage hints raise it to 4.

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

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

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

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

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

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

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds useful behavioral context beyond that: it routes internally, fills arguments, returns a structured answer with stable citation URIs, and works on every tier as a single fast call. It does not discuss failure modes or rate limits, but those are not critical given the annotation set.

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-structured: it front-loads the preference instruction, gives concrete categories and examples, then clearly separates 'START HERE' from 'Step up only when needed'. Each sentence adds practical value for tool selection and invocation.

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 broad default entry-point tool, the description is remarkably complete: it covers when to use it, what it returns, how it differs from alternatives, examples of queries, and even news routing behavior. No output schema exists, but the description sufficiently describes the expected structured citation return.

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 the schema documents every alias for the question parameter. The description itself does not add parameter-level guidance, but with full schema coverage the baseline of 3 applies. The schema examples further clarify expected input formats.

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

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

Description states exactly what ask_pipeworx does: it takes natural-language factual questions, routes them to one of 5,743 source tools, and returns structured answers with pipeworx:// citation URIs. It also clearly positions itself as the default entry point versus siblings like ask_pipeworx_grounded and deep_research, so an agent can distinguish 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?

Gives explicit when-to-use guidance: prefer over web search for a wide range of factual/current-data questions, and use specific trigger phrases like 'what is', 'look up', 'find', 'current'. It also provides clear alternatives: use ask_pipeworx_grounded for a grounded single answer and deep_research 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 provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds non-obvious behavioral context: candidate routing improvements enabled live, no candidate active as of a specific date, exact matching with ask_pipeworx when no candidate is active, and a guarantee that this is a full working router with no fallback. This is substantial value 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 front-loaded with the tool's identity and current behavior, and each sentence adds useful context such as live candidate testing, current parity with ask_pipeworx, and the no-fallback guarantee. There is minor redundancy in saying 'identical' and then 'matches ask_pipeworx exactly' and 'use it exactly like ask_pipeworx,' but the text remains efficient.

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

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

For a single-required-parameter router with rich annotations, the description sufficiently covers current behavior, usage guidance, experimental status, and comparison to the stable router. It delegates response shape to ask_pipeworx rather than explaining it, which is reasonable given the sibling tool is available, but a bit more standalone detail would make it fully complete.

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

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

The input schema documents the required 'question' parameter and all five aliases with 100% coverage. The description does not add new parameter semantics beyond referring to 'same arguments' as ask_pipeworx, so the schema carries the burden and the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and as a universal router with the same 5,743 tools, arguments, and response shape. It distinguishes it from the stable sibling by its experimental/candidate status, though it leans on the sibling's name rather than defining the core behavior fully standalone.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It provides useful context about the current no-active-candidate state, but it does not explicitly state when not to use it or how it compares to ask_pipeworx_grounded.

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/idempotent annotations, it discloses refusal behaviors with exact refusal_reason values, the evidence-quote return field, the extra LLM call cost, and the constraint that it uses only tool-result content. This is rich behavioral context the annotations do not provide.

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

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

The description is dense but every sentence earns its place: core mode, routing mechanism, return/refusal shapes, use cases, and cost trade-off. It is front-loaded with the most important phrase and avoids 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 compensates fully: it enumerates the success shape, failure shape, refusal reasons, usage context, and cost comparison. An agent has everything needed 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 input schema already has 100% coverage, describing 'question' and all aliases. The description does not add new parameter-level meaning; it focuses on internal behavior. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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: 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It explicitly distinguishes itself from ask_pipeworx by the grounded extraction behavior and names the sibling alternative.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear exclusion and alternative: 'prefer ask_pipeworx for casual lookups.' No inference is required.

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

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

Disclosures far exceed annotations. Details resolution pipeline, fan-out logic, confidence matching, parent event extraction, news fallback, safety short-circuits, spread warnings, and cancellation rule parsing. ReadOnlyHint is confirmed; no contradictions.

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

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

While comprehensive, the description is dense and lengthy (multiple paragraphs). However, it is front-loaded with a clear summary and uses sectioning (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to aid scanning.

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

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

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

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds value: explains market input formats (slug, URL, question), depth defaults, and include_raw behavior. Clear examples further aid selection.

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

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

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

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

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

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

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

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

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

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

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

Description is dense but efficient, front-loading example queries and using shorthand like 'AAPL Sep, NVDA Jan'. Every sentence serves a purpose, stating scope, data sources, sorting, and return format. No fluff.

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

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

Despite no output schema, description sufficiently explains return data (paired results, sorted by metric, with citation URIs). For a complex comparison tool with two entity types and multiple data sources, the description covers all key behavioral aspects, making it complete for agent invocation.

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

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

Schema coverage is 100%, but description adds meaning: explains that type='company' pulls financials and type='drug' pulls adverse-event/trial data, and how to format values (tickers/CIKs for companies, names for drugs). This is beyond the schema's enum and array description.

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

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

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

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

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

Provides concrete usage examples 'Compare X and Y', 'which is bigger', and explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance and when-not-to (avoid sequential lookups).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context beyond those: the account/paid-plan requirement, parallel decomposition across 5,743 tools, the findings-packet shape with gaps[] and contradictions[], stable citeable pipeworx:// URIs, semantic excerpting of large records, and latency expectations. It discloses that the tool "never invented" data and that unpresent topics yield empty gaps[].

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 deliberately dense and front-loaded with the most critical caveat (account required, paid tier for thorough). Each clause earns its place by describing a distinct behavior or exclusion. Slight redundancy exists between the schema's depth descriptions and those in the text, but for a tool of this complexity the length is justified.

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

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

With no output schema, the description must carry the full burden of explaining return values, and it does: verbatim evidence, confidence, source, fetched_at, a stable pipeworx:// citation per finding, gaps[], contradictions[], and the hop field. It also covers prerequisites, latency, and fallback paths, leaving nothing an agent needs to decide correct invocation or interpret results.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful context by explaining what "broad/multi-part" questions are appropriate, clarifying that quick/standard/thorough differ in facets, hops, and contradiction scanning, and explicitly tying depth to timing. It reinforces the schema's enum semantics rather than repeating them verbatim, earning an above-baseline score.

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

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

The description states a specific verb and resource: "Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call." It clearly distinguishes itself from siblings with "this is NOT open-web search" and names ask_pipeworx as the alternative for different use cases. An agent can immediately understand the tool's unique role among the 34 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?

The description gives explicit when-to-use and when-not-to-use guidance: "If you are not signed in, use ask_pipeworx instead", "For a single lookup use ask_pipeworx", and "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx." It also explains how depth levels map to different investigation strategies, making the decision process concrete for the agent.

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

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

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

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

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

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

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

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

Given the tool's purpose (discovery), parameter count, and absence of output schema, the description covers all essential aspects: when to use, what to expect, how results are structured, and strategic guidance. It is complete for the intended use case.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by listing example queries and providing a list of data domains, which helps the user understand what kinds of queries are appropriate. It also mentions aliases (though already in schema). This enhances parameter understanding.

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

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

The description clearly states the tool's purpose as 'Find tools by describing the data or task', using a specific verb and resource. It distinguishes itself from sibling tools by explicitly being for discovery and browsing, and lists numerous data domains, making it clear what it covers.

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

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

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

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior, and the description adds substantial behavioral context: it fans out across SEC, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF; it discloses the USPTO PatentsView API sunset in May 2025 with soft-failure; it explains sources_used/sources_failed semantics; and it notes that an empty section is real 'no data', not a bug. This far exceeds what annotations alone convey.

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

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

The description is front-loaded with real user phrases and the key usage preference, which is ideal. It is long because it enumerates many return sections and failure modes, but each detail serves the agent's decision-making. It could be tightened slightly, but the length is largely justified by 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 present, the description carries the full burden of explaining return values, and it does so exhaustively: it lists every returned field, provides URI formats for filings, describes fallback behavior from GDELT to GNews, states what a private-company result looks like, and explains source-level failure reporting. An agent has enough context to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful nuance beyond the schema by explaining that 'type' accepts 'company' or 'ticker' interchangeably, that value may be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR's company-name match. These examples and clarifications help disambiguate expected inputs without being redundant.

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 produces a 'full cross-source profile of a US public company' from multiple sources in one call. It uses concrete user phrasings ('Tell me about X', 'research Acme', 'brief me on Tesla') to signal intent, and it distinguishes itself from 'chaining single-pack SEC/XBRL/news lookups', so an agent can tell it apart from narrower 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?

The description contains an explicit usage directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies boundary cases such as private companies returning resolved:false with a notes line rather than a failure, and expected empty sections for companies without certain data types. This gives clear when-to-use and when-not-to-worry guidance.

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

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

Annotations indicate destructiveHint=true, and description confirms deletion. Adds context on why deletion is performed (stale context, done task, clear sensitive data), aligning with annotations.

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

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

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

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

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

Given the simple tool (1 param, no output schema, no nested objects), the description fully covers purpose, usage, and behavior.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Given simple parameters and no output schema, the description adequately explains output format ('single text blob', 'standard llms.txt markdown'). Could mention that output is plain text, but sufficient.

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

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

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

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

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

The description specifies a clear verb ('Generate') and resource ('llms.txt file for any URL'), and differentiates from siblings by focusing on AI crawler indexing. It is not a tautology and provides concrete details.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), giving context for when to use. Does not explicitly state when not to use, but the positive guidance is strong.

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

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

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

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

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

The description is extremely concise, fitting into a single sentence. While it is efficient, it risks being under-specified. Every word is necessary, but more detail could be added without harming conciseness.

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

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

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

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

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

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

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

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

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

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

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

No guidance is provided on when to use this tool versus alternatives such as 'list_versions'. The description does not indicate prerequisites, constraints, or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying it lists only active subscriptions by default and the return fields. No contradiction.

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

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

Two sentences: first states action and return fields, second gives usage guidance. No filler. Highly efficient.

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

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

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

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

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

Schema covers the only parameter (include_inactive) with a description. Description adds minimal extra context by saying 'active' subscriptions by default, which relates to the parameter. Schema coverage is 100%, baseline 3 is appropriate.

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

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

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

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

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

States when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides context but no direct 'when not to use' or alternatives beyond implied differentiation from subscribe/unsubscribe.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds minimal extra behavioral context (uses Maven Central Solr GAV core). It does not contradict annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds critical behavioral context: monotonicity checks, partition checks, fill check against CLOB depth, semantic anchor (Jaccard similarity), partition filter (placeholder slug handling). No contradiction with annotations.

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

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

The description is dense and well-organized, starting with purpose, then modes, then detailed behavior per parameter, then fill check, then sibling reference. However, it is somewhat verbose; some sentences could be compressed without losing meaning (e.g., the semantic anchor explanation). Still, every sentence adds value.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: caching at 1h, internal model details, and limitations (e.g., Fed bets unreliable without paid data). No contradictions found.

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

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

The description is very long and dense, packed with technical details and parentheticals. While informative, it lacks conciseness and clear structure (e.g., no bullet points), making it harder to parse quickly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: return structure (tracked, expired, snapshot_dates), decay computation (on |edge_pp_net|, signed), and data gaps (snapshots written on cache misses). No contradiction with annotations.

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

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

The description is dense but well-organized, front-loading the core purpose. Every sentence adds information. Could benefit from bullet points for return fields, but overall efficient for the complexity.

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

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

For a tool with no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and their contents. It also covers limitations (60-day TTL, intraday not available), making it complete for agent invocation.

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

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

Schema covers both parameters (days, window) with descriptions. The description adds clarity by repeating defaults and clamp values, and by explaining the effect of each parameter (lookback, snapshot family). This adds marginal value beyond the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% but the description adds significant context: clarifies that 'event' and 'market' are mutually required, explains the default side logic for basket mode (auto from partition sum), and interprets size_usd differently for single-market vs basket ('spend on buys, target proceeds on sells' vs 'settlement notional'). This goes well beyond schema descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes two modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use this tool before acting on their outputs.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear context for when to use. It does not explicitly state when not to use, but the strong positive guidance implies thresholds. It also warns about partial fill risks.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds far more: pairing_unverified, compatibility_codes, temporal alignment unknowns, non-equivalent bet shapes, skipped-leg counters, and the gross-vs-net fee caveat. This is exemplary disclosure 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 long but deliberately structured with TWO MODES, SAFETY FIELDS, and Codes sections, and each sentence introduces a distinct caveat or behavior. It is dense rather than redundant, but the sheer length prevents a perfect conciseness score.

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

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

There is no output schema, so the description carries the full burden of explaining results; it does so thoroughly, covering leg prices, spread entries, compatibility flags, temporal alignment, skipped comparisons, and fee treatment. An agent has enough information to call the tool and interpret its output 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 the baseline is 3; the description adds genuine value by explaining mode semantics and how explicit parameters override topic-mapped sides. It enriches the parameters enough to earn a 4, though the schema already carries the basic definitions.

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

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

States a specific deliverable: cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates the tool from sibling Polymarket-only tools by explaining the two-venue delta and the conditions under which it is meaningful.

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 explains the two invocation modes, when to use topic shortcuts vs explicit ticker/slug pairings, and warns that pre-mapped topics are frequently not tradeable. It does not explicitly name an alternative sibling for single-venue analysis, so it falls just short of full 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=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping and pairing with siblings but does not disclose additional behavioral traits beyond that. No contradictions.

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

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

Two concise sentences covering purpose, usage, and relationships with siblings. Every sentence is informative and front-loaded. No wasted words.

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

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

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

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

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

Schema coverage is 100% with clear parameter description. The description's main text echoes the schema's parameter explanation but adds no extra semantic value beyond what the schema already provides.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull), and details the return fields. While not explicitly distinguishing from siblings, the purpose is specific and unambiguous.

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

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

The description provides guidance on when to use ('Pull fired events...'), mentions that 'Polls work fine' indicating suitability for polling, and gives an alternative endpoint for scripts/dashboards. It does not explicitly exclude use cases but offers useful context for appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral details: parallel fan-out, GDELT>GNews fallback, USPTO soft-failure, and return structure. No contradictions.

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

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

The description is front-loaded with example queries and well-organized. It conveys all necessary information without excessive verbosity, though could be slightly more concise.

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

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

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

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

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

Schema coverage 100% gives baseline 3. The description adds extra meaning: explains 'since' format with examples, notes only 'company' type supported, and clarifies 'value' can be ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company in a time window by fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It differentiates from sibling entity_profile for static profiles.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% (both key and value described), so baseline is 3. The description adds examples of key names (subject_property, target_ticker, user_preference) and value types (findings, addresses, preferences), enhancing the schema's generic descriptions.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It gives specific examples like 'resolved ticker, target address, user preference, research subject,' which distinguishes it from sibling tools like recall and forget.

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

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

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

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

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

Beyond the annotations already declaring readOnly, idempotent, open-world, and non-destructive behavior, the description discloses many important behaviors: graceful degradation when GLEIF/OpenFIGI are unavailable, returning figi_candidates on ambiguous matches, explicitly listing unresolved identifiers, labeling identifiers by source, and internally cascading through multiple endpoints. This is far more behavioral context than 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 extremely dense and packed with valuable detail, but it is structured as one long run-on paragraph with heavy parentheticals. The front-loaded query examples and 'Use FIRST' directive are strong, but the lack of bullets or separation makes it harder to scan than necessary.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: resolved identifiers by source, unresolved handling, ambiguity behavior, failure degradation, accepted input forms, and type-specific details. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value by documenting ISIN as an accepted input for company type (which the schema does not list) and explaining how the value is interpreted differently for company vs drug. It enriches parameter meaning beyond the schema's basic field descriptions.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also gives concrete query paraphrases and the directive 'Use FIRST whenever you have a name but need an ID,' which clearly differentiates it from sibling tools that consume IDs.

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 usage condition: use FIRST whenever the agent has a name but needs an ID, and it explains that the tool replaces 2-3 manual lookups. It does not name specific sibling alternatives or state when not to use it, so it lacks explicit exclusions, but the context is clear and actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behavioral details: calls ai_visibility_check internally, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density per entity. No contradictions with annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds key behavioral context: partial failures degrade gracefully, bundlephobia's first call can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

Single paragraph but well-structured: starts with overview, lists return fields, mentions ecosystem, adds performance note. Dense but not verbose; slightly long but every sentence adds value.

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

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

No output schema, so description details all return fields: summary block fields, per-advisory detail, links, alternative versions. Also covers partial failure behavior. For a composite tool with 2 parameters, this is complete and actionable.

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

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

Schema has 100% coverage with clear descriptions. Description adds context: package accepts scoped names, version defaults to latest, and explains the composite nature. Adds value beyond schema by clarifying defaults and scope.

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

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

The description clearly states the tool performs a composite check for npm packages, covering license, advisories, version history, and bundle size from two services. It specifies the verb 'fans out across' and differentiates from sibling tools by limiting to NPM ecosystem in v1.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and clarifies NPM scope, directing other ecosystems to deps.dev directly. This provides clear when-to-use and alternatives.

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

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

Annotations already confirm readOnly, idempotent, non-destructive. Description adds that results are limited to 200 matches and includes what is returned (coordinates, latest version, timestamps). No contradictions.

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

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

Single sentence clearly states purpose, scope, and output. No extraneous words. Front-loaded with the action and resource.

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

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

For a simple search tool with 3 parameters and output schema, the description adequately covers purpose, search fields, result limit, and output fields. Lacks pagination details but schema covers start and rows.

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

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

Schema coverage is 100% with each parameter described (query, rows, start). Description does not add significant new meaning beyond schema, but provides context that search is on Maven Central packages.

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

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

Description clearly states 'Full-text search across Maven Central packages' with specific fields (groupId, artifactId, version, tags) and output details (coordinates, latest version, download timestamps, up to 200 matches). This distinguishes it from siblings like search_by_coords and search_within.

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

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

Description implies general search usage but does not explicitly state when to prefer it over alternatives like search_by_coords or search_within. No exclusions or when-not-to-use guidance provided.

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

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

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

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and usage pattern.

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

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

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

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by emphasizing 'any combination', which clarifies that parameters are optional and can be used flexibly. This goes beyond the schema's individual parameter descriptions.

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

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

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

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

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

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

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral details: underlying model (BGE-base-en), chunking (500-char overlapping windows), limit (200K chars truncated and flagged), and return fields (character offsets, similarity scores). No contradiction with annotations.

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

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

The description is concise: two sentences plus a technical note. It is front-loaded with purpose and usage, and every sentence earns its place without redundancy.

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

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

Despite no output schema, the description explains return format (passages with offsets and similarity scores) and behavior for oversized inputs (truncation flagged). This is complete for a search tool.

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

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

Schema description coverage is 100% with each parameter described. The description adds examples for 'query', clarifies the cap for 'text', and mentions default for 'limit'. This adds value beyond the schema, though schema is already good.

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

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

The description clearly states the tool does semantic search inside a fetched record. It uses specific verbs and resources, and distinguishes from siblings like 'search' and 'ask_pipeworx_grounded' by emphasizing internal search over a provided text.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded.' This helps the agent choose wisely.

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

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

The description adds substantial behavioral context beyond the annotations: it notes the tool requires authentication, returns a new subscription ID, details delivery channel constraints (SMS cap, webhook auto-disabling, signing), and explicitly lists supported types with examples. Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description does not contradict them.

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

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

The description is front-loaded with the core purpose, followed by requirements, types, and delivery details in a logical order. Every sentence provides unique information without redundancy. It is appropriately sized given the complexity of the tool.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it is an onboarding entry point that returns example questions and can be filtered by topic. No contradiction with annotations.

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

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

The description is moderately long but well-structured. It front-loads alternative phrasing and then gives a clear breakdown of what the tool returns, how to call it, and when to use it. Every sentence adds value, though minor trimming could improve conciseness.

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

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

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

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

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

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

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

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

The description explicitly states the tool returns 'category-bucketed example questions' with 'exact tool + argument shape', and positions itself as an onboarding entry point. This clearly distinguishes it from siblings like 'ask_pipeworx' (which answers questions) or 'discover_tools'.

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

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

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

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds valuable context: deactivation (not deletion) and preservation of historical events via recent_alerts. No contradiction.

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

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

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

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

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

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

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

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

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

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

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

The description uses a specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from siblings like 'subscribe' (create) and 'list_subscriptions'. It also adds ownership scope.

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

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

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

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

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

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

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

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

The description is detailed but every sentence earns its place: trigger phrases, routing logic, return contract, and caveats. It is front-loaded with the core purpose and ends with operational warnings. There is no redundant content.

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

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

With no output schema, the description fully documents the return value (verdict enum, actual value with citation, reasoning) and explains edge cases like could_not_verify and unsupported. Given the tool's complexity (routing, tolerance, error handling), the description is remarkably complete.

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

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

Schema coverage is 100% for both parameters, but the description enriches them: it gives realistic examples for claim, and for tolerance_pct it explains the default behavior, the override mechanism, and recommends 1–2 for hallucination detection. This adds meaning beyond the schema's bare field descriptions.

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

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

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

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

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

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

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