colorapi

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds value by disclosing the default model, the need for an Anthropic API key, and the cost implication ('you pay Anthropic directly'), which is beyond what annotations provide. It also reveals return structure.

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

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

The description is three sentences, front-loaded with the primary function, followed by model configuration details and use cases. No wasted words; every sentence contributes distinct information.

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

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

The tool has 4 parameters with full schema coverage and no output schema. The description compensates for the missing output schema by describing the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also explains model options and use cases, though it does not cover error scenarios or edge cases.

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 explained (entity, models, _apiKey, context). The description largely restates what the schema already says, with the additional note about direct payment to Anthropic, but this adds marginal semantic 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's action ('Probe one or more LLMs'), the subject ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model LLM visibility scoring rather than general presence scanning.

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

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

The description gives concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly mention when to prefer this over sibling tools or any exclusions, so it doesn't fully meet the 'when/when-not/alternatives' bar.

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 meaningful behavioral details beyond the annotations: it routes questions across thousands of tools, fills arguments automatically, and returns structured answers with stable citation URIs. This is valuable context and does not contradict the readOnly/openWorld/idempotent hints, though it omits failure behavior and rate-limit or latency characteristics.

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 opening is front-loaded and well written, but the description repeats the same multi-sentence block verbatim multiple times — 'PREFER OVER WEB SEARCH... START HERE for most questions' — creating substantial redundant bloat. The unique content earns its place, but as written the repetition wastes tokens and hurts usability.

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 router tool with no output schema, the description is largely complete: it covers domains, trigger phrases, examples, argument-filling behavior, and the return format with citations. It could add edge-case guidance such as what happens when no matching source exists or whether results are live versus cached, but the core selection and invocation context is 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?

The schema already documents the single semantic parameter and its aliases with 100% coverage, so the baseline is 3. The description adds value by clarifying that the question parameter is a high-level request and that the tool itself 'fills arguments', meaning the agent can pass a broad natural-language query without needing to specify sub-arguments.

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

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

The description clearly identifies the tool's role: it routes a natural-language question to one of 5,798 tools across verified sources and returns structured answers with stable pipeworx:// citation URIs. It is specific about verb, resource, and scope, but it does not differentiate from close siblings such as ask_pipeworx_beta or ask_pipeworx_grounded, so it does not fully meet the top criterion.

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

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

The description gives explicit usage triggers: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks "what is", "look up", "find"...' with concrete examples. It also says this tool should be preferred even when web search could answer. However, it does not mention exclusions or close sibling alternatives like ask_pipeworx_grounded or ask_pipeworx_beta.

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 flag readOnly, openWorld, idempotent, and non-destructive behavior. The description goes well beyond those by disclosing that candidate routing improvements are enabled live, that no candidate is currently active, that the tool matches ask_pipeworx exactly today, and that there is no fallback—it is a full working experimental router. This gives the agent an unusually clear picture of what to expect.

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: identity, relationship to the stable router, current active state, usage guidance, comparison purpose, and fallback behavior are all covered. The key fact—'same 5,798 tools, same arguments, same response shape'—is front-loaded, and the experimental nature is made explicit without repetition.

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

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

Despite having no output schema, the description states the response shape is identical to ask_pipeworx, so the agent knows what to expect. It covers current operational state, how to use it, what distinguishes it from the stable tool, and what happens when candidates are active. For a routing tool with one required parameter and rich annotations, nothing essential is missing.

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 aliased and documented as a natural-language question or request. The description adds no new parameter-level meaning, but it does state 'same arguments' as ask_pipeworx, reinforcing that the schema is complete. Baseline 3 is appropriate because the schema already carries the parameter semantics fully.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, explicitly stating it is a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting candidate routing improvements, and the current 'matches ask_pipeworx exactly' clarifies its present behavior. This is specific, actionable, and differentiates it from siblings.

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 this 'exactly like ask_pipeworx when you want the newest routing,' giving a clear positive condition for use. It references the stable router as the comparison baseline and notes experiments drive merges, implying stable ask_pipeworx is the alternative for non-experimental use. It stops short of an explicit 'do not use when...' statement or mention of ask_pipeworx_grounded, so slightly short of a perfect 5.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive hints, and the description adds substantial behavioral detail beyond them: hallucination resistance, answer extraction limited to the tool result, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the extra LLM call cost. No contradiction with annotations.

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

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

Three dense sentences, each with a distinct purpose: defining the mode, specifying the output/refusal contract, and giving usage guidance plus cost tradeoff. Information is front-loaded with the key differentiator (hallucination-resistant) and no filler.

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

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

For a tool with no output schema, the description fully explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal paths. It also covers routing, source scale, cost, and when to prefer the sibling, making it complete for correct invocation and interpretation.

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%: every parameter (the question and its five aliases) is described in the schema itself. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: an answer mode that extracts answers only from tool results, with explicit output and refusal structures. It distinguishes itself from ask_pipeworx by naming the grounded/hallucination-resistant behavior and the cost tradeoff, so an agent can tell them apart.

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

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

Explicit usage criteria are given: use when answers will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples (financial, legal, medical, public statements). It also provides an alternative and a preference rule: prefer ask_pipeworx for casual lookups.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: parallel fan-out, response shapes, resolver confidence levels, parent-event extraction, news fallback handling, low-confidence short-circuiting, closed-market status, wide-spread tradeability, and cancellation-rule risk. This goes far beyond the structured annotations and gives the agent critical operational knowledge.

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

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

The description is long but well-structured with clear uppercase section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) that make it scannable. Every section adds necessary detail for a complex tool with no output schema. It could be slightly condensed, but the density is warranted.

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 (3 params, no output schema, many behavioral edge cases), the description is remarkably complete. It comprehensively documents return shapes, resolver confidence, parent-event data, news fallback behavior, safety statuses, and cancellation-rule risk. An agent has enough information to use the tool correctly and interpret results without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining input formats (slug, URL, question text) with examples, elaborating on the 'thorough' fan-out via the FAN-OUT EXAMPLES, and clarifying the impact of 'include_raw' on response size. This supplements the schema without redundancy.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (single bet research with evidence fan-out) from sibling tools like polymarket_edges or polymarket_arbitrage, and explicitly states the use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

The description provides explicit 'Use for' guidance with concrete example queries, and explains the fan-out process and safety short-circuits. It does not explicitly name alternative tools or state when not to use this tool, but the use cases are clear enough to guide an agent. Sibling differentiation is implicit via purpose rather than direct comparison.

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

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

With annotations already declaring readOnly, idempotent, and openWorld safety, the description adds substantial behavioral detail: type='company' pulls specific SEC EDGAR/XBRL fields (10-K revenue, net income, cash, long-term debt) with correct handling of off-calendar fiscal years; type='drug' pulls FAERS, FDA approval, and trial counts; results are sorted by primary metric; output includes paired data and citation URIs. This goes well beyond the annotation baseline.

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 trigger phrases and immediately stating the tool's purpose. Every sentence carries meaningful detail (data sources, fiscal-year handling, sorting, citation URIs, efficiency claim). It's longer than ideal but earns its length given the tool's dual-type complexity. Slight reduction in verbiage could improve it, earning a 4 rather than a 5.

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

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

The description covers the tool's function, input semantics, data-fetching behavior, output format (paired data + citation URIs), and sorting logic. It also sets expectations about scale (replaces 8–15 lookups). Without an output schema, it doesn't fully specify the response structure but does give enough for an agent to infer. Missing minor details like pagination or error cases, but for its complexity, it's largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains what each type's data sources are (e.g., latest 10-K for company, FAERS/FDA/trials for drug), provides concrete examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"], and clarifies that sorting is by primary metric. This enriches the meaning of both 'type' and 'values' significantly.

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 explicit trigger phrases ("Compare X and Y") and defines the exact action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sibling tools by noting it replaces 8–15 sequential single-pack lookups, clearly positioning it as a batch comparison tool rather than a single-lookup 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?

Explicit guidance is given: "ALWAYS PREFER over sequential single-pack lookups when comparing entities," along with concrete use cases (ranking, head-to-head, which is bigger). However, it doesn't name alternative sibling tools like entity_profile or search_within directly, only refers to them generically as "sequential single-pack lookups," leaving some ambiguity for an AI agent unfamiliar with the sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description additionally discloses that it returns the closest named color and lists output formats, providing behavioral detail beyond the safety annotations. There is no contradiction.

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

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

The description is a single sentence that front-loads the core purpose and output. It is concise with no redundant phrasing, achieving high information density.

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 input (three integers) and the presence of an output schema, the description adequately covers the tool's behavior. It explains both conversion and color naming, and with annotations and schema, it is complete for effective 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?

The input schema covers 100% of parameters with descriptions for r, g, b (0-255). The description adds no parameter-specific syntax beyond what the schema provides, but the schema itself is sufficient. Baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Convert' with the resource 'color formats' and lists the exact conversions (RGB to hex, HSL, HSV, CMYK) plus a named color output. This clearly distinguishes it from siblings like identify_color, which focuses solely on color naming.

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 its use for color format conversion but does not explicitly state when to use it over siblings like identify_color or provide exclusions. It gives context but lacks explicit alternatives or when-not-to-use guidance.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context: account/paywall requirements, gaps[] that are never invented, contradictions[] scanning, citation provenance, semantic excerpting, and 15-90s latency expectations. No statement contradicts the annotations.

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

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

The description is long but every sentence carries load-bearing information: auth, alternatives, mechanism, output contents, depth nuances, citation resolvability, and latency. It front-loads the most critical operational constraint, the account requirement and fallback tool, before describing mechanics.

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 specifies what is returned: evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers auth, depth differences, latency, and handling of large records, so an agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100% and both parameters are already well documented in the input schema, so the baseline is 3. The description reinforces depth behavior and adds account/paywall context and question examples, but it does not materially change how an agent should format either parameter.

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 names a specific operation: grounded multi-source research across 1,517 structured data sources in one call, with decomposition and parallel routing to 5,798 tools. It also distinguishes itself from open-web search and from ask_pipeworx, making sibling differentiation clear.

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 ('Best for broad/multi-part questions over structured data'), explicit alternatives ('For a single lookup use ask_pipeworx instead'), and sign-in requirements. It also explains depth-level tradeoffs, so an agent knows exactly when to select this tool over siblings.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description goes beyond by detailing 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 adds valuable context about output and eliminates ambiguity.

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 usage guidance, then return details, and closes with tactical advice. Every sentence adds distinct value, and no filler is present. Length is justified for a discovery tool that needs to convey its expansive scope.

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

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

Given no output schema, the description compensates by explaining exactly what will be returned (names, descriptions, full schemas, curated examples) and the benefit of being call-ready. It also covers the broad range of supported data domains, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, and the schema already explains the 'query' parameter with aliases and examples. The description says 'by describing the data or task' which aligns with the schema but does not add new parameter-level details. Baseline 3 is appropriate since the schema carries the load.

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 verb and resource: 'Find tools by describing the data or task.' It distinguishes itself from siblings by positioning as a meta-tool for discovery ('Call this FIRST when you have many tools available'), which is unique among the listed 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a when-not condition: 'not just one answer.' It also gives strategic advice to call this tool first when many tools are available, which serves as clear usage 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?

Goes far beyond the annotations (readOnly, idempotent, openWorld) by detailing what each return section means, including edge cases like FDA products being empty for generic-only companies and patents soft-failing after May 2025. Explicitly states that empty sections are real 'no data' and not bugs, and explains sources_used/sources_failed semantics. 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?

Although long, every sentence carries information. The structure front-loads example queries, lists return sections concisely with parenthetical clarifications, and handles edge cases in-line. No filler or redundancy. The length is appropriate for the tool's complexity.

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

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

The description covers all aspects that an agent needs: input variants, return fields (cik, filings, fundamentals, patents, etc.), failure modes (empty sections, private companies, patent API sunset), and the meaning of sources_used/sources_failed. With no output schema, the description fully compensates by detailing return structure.

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%, giving both parameters full descriptions. The description adds value by explaining that 'type' accepts company or ticker interchangeably and that 'value' can be any of three forms. It also clarifies that names resolve via SEC EDGAR matching, which is not obvious from the schema alone.

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

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

The description states a clear verb+resource: produces a 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the exact sources and return sections, distinguishing it from siblings like compare_entities and resolve_entity. The opening example queries make the purpose immediately recognizable.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Provides input formats (ticker, CIK, name) and clarifies when it will not resolve (private companies yield resolved:false). No sibling exclusion is needed because the scope is clearly defined.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the mutation and idempotency aspects. The description adds context about clearing sensitive data and stale context, but does not disclose additional behavioral traits such as error handling on non-existent keys. 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 compact, consisting of two sentences. The first sentence front-loads the core purpose, and the second provides usage guidance and tool pairing. Every sentence earns its place with no redundancy or filler.

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

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

For a simple tool with one parameter, no output schema, and robust annotations (destructive, idempotent), the description is complete. It clearly explains what the tool does, when to use it, and how it relates to sibling tools. No critical information is missing.

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%: the only parameter 'key' is described as 'Memory key to delete' in the schema. The description's 'by key' adds no new meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific action: 'Delete a previously stored memory by key.' This clearly states the tool's function and resource. It also distinguishes itself from siblings by explicitly pairing with 'remember' and 'recall,' making its role as the deletion counterpart unambiguous.

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions related tools via 'Pair with remember and recall,' but does not explicitly state when not to use this tool or name an alternative to choose instead, so it falls short of the top score.

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 idempotentHint=true, so the safety profile is covered. The description adds behavioral context by explaining the process: fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format, plus noting the output is a single text blob. This goes beyond the annotations.

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

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

The description is three sentences, each earning its place: the main action, the process and output, and use cases. It is front-loaded with 'Generate a production-ready llms.txt file' and contains no filler or redundancy.

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

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

For a simple read-only tool with complete schema and annotations, the description covers the output format ('single text blob ready to drop at site-root/llms.txt') and usage scenarios. Minor details like error handling on invalid URLs are missing, but they are not critical given the tool's simplicity and annotation coverage.

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

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

The schema covers both parameters (url and max_links) with full descriptions, achieving 100% coverage. The tool description does not add significant parameter-specific detail beyond reinforcing that url is a site URL and mentioning the extraction of key links, but the schema already handles this sufficiently. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file', and specifies the exact output format and purpose. It distinguishes itself from sibling tools like ai_visibility_check by focusing on generating a file for AI crawler indexing.

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

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

The description lists three specific use cases: getting a client's site indexed, drafting llms.txt for one's own project, and auditing a competitor's AI visibility. This gives clear context on when to use the tool, though it does not explicitly name alternative tools or exclusions, which prevents a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful behavioral context by specifying that it returns complementary, analogous, triadic, or monochromatic schemes with hex codes. However, the example input with a '#' prefix conflicts with the schema's requirement, slightly undermining clarity.

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

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

The description is a single sentence that front-loads the purpose and includes a concrete example. Every word earns its place, with no redundant phrasing or unnecessary details.

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

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

For a simple tool with an output schema and good annotations, the description is mostly adequate. However, the input format mismatch regarding the '#' prefix and the inconsistent mode names create gaps that could lead to incorrect invocations.

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 no extra semantic value and actually introduces conflicting terminology (e.g., 'monochromatic' vs the schema's 'monochrome', and the example '#3498DB' with a '#' even though the schema expects no '#'). This could mislead an agent into providing invalid parameters, warranting a below-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 clearly states the tool's function with a specific verb ('Generate'), a defined resource ('harmonious color palettes'), and a required input ('seed hex color'). It distinguishes itself from sibling tools like convert_color and identify_color by focusing on palette generation.

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 the tool should be used for generating color schemes, but it provides no explicit guidelines on when to use this tool instead of alternatives such as convert_color or identify_color. No exclusions or alternative references are mentioned.

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 the tool is read-only, idempotent, and non-destructive. The description adds transparency by detailing the returned data (color name, RGB/HSL/HSV/CMYK, WCAG contrast ratios), which goes beyond the annotations and helps the agent anticipate the tool's output.

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

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

The description is a single, well-structured sentence that front-loads the tool's purpose and includes a concrete example. Every word adds value, and there is no redundancy or unnecessary detail.

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

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

The tool is simple (one parameter, read-only), and the output schema exists to define return structure. The description covers what the tool does and what it returns, while annotations cover safety and idempotency. The combination leaves no significant gaps for an agent to safely invoke the tool.

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

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

The schema fully describes the only parameter 'hex' with format and example, achieving 100% schema coverage. The description repeats this information without adding new semantic value, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: identify a color by hex code. It specifies the exact input format and enumerates the outputs (name, RGB/HSL/HSV/CMYK, WCAG contrast ratios), making it distinct from siblings like convert_color.

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

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

The description provides clear context for when to use the tool: when you need to identify a color and obtain its name, color space values, or contrast ratios. It does not explicitly mention alternative tools or exclusions, but the use case is well implied.

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 and destructiveHint=false. The description adds behavior beyond annotations: results are scoped to the caller, only active subscriptions are listed by default, and the exact return fields are enumerated. This is useful contextual information not present in 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?

Two concise sentences: the first states purpose and return fields, the second provides contextual usage guidance. No redundant words or formatting issues.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, scope, output fields, and usage context. The annotations cover safety semantics, making this 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 for the only parameter (include_inactive) is 100% with a clear description. The tool description reinforces that active subscriptions are shown by default but does not add new meaning beyond the schema. Baseline 3 is appropriate when schema fully covers parameter 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 opens with 'List the caller's active subscriptions' – a specific verb+resource with clear caller scoping. It distinguishes itself from subscribe/unsubscribe siblings by framing it as a review step before adding or canceling.

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

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

Explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly states when to use the tool in relation to subscribe and 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 carry no positive safety hints (all false), so the description carries the burden. It discloses rate limiting (5/day), that it is free and doesn't count against quota, the claim_token workflow for anonymous filing, and that the team reads digests daily—far beyond the structured fields.

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

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

Long but front-loaded and dense with purpose; the first sentence states the core action and the rest expands with scoping, workflow, and policies. Every sentence adds operational value (quota, token, exclusion), so 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 four parameters, one enum, and nested context, the description is thorough: it explains the exact scenarios, the distinction from non-Pipeworx tools, the claim_token retrieval flow, and rate limits. No critical behavioral gap remains.

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 100% of the four parameters, so baseline is 3. The description adds a workflow detail the schema does not: filing without an account returns a claim_token and shows how to call it later with pipeworx_feedback({claim_token:"pwfb_…"}). This raises 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 opens with a concrete action—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and reinforces it with explicit use cases (bug, feature/data_gap, praise). It clearly separates this feedback channel from sibling tools like ask_pipeworx/discover_tools and explicitly scopes it to tools served by this connection.

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 triggers for each report type and a strong exclusion: tools from other MCP servers should be filed there, not here. It also resolves ambiguity by telling users that Pipeworx tool names are the ones this connection lists.

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 this is a safe, read-only, idempotent operation. The description adds valuable context beyond that: data originates from CF analytics-engine, contains no PII, exposes only (pack, tool, count), and is cached for 5 minutes to 1 hour depending on the window. This gives the agent a good sense of freshness and privacy characteristics without overloading the description.

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

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

The description is front-loaded with the core purpose and outputs, followed by use cases and a transparency note. It is slightly longer than minimal due to the three-item 'Useful for' list, but each item conveys unique guidance, and the overall structure makes it easy to scan. A minor trim could make it even tighter, but it earns its length.

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

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

This is a simple, read-only tool with one optional parameter and no output schema. The description adequately covers return value shape ('top tools, top packs, call volume', 'just (pack, tool, count)'), use cases, caching, and privacy. It could be more explicit about exact response formatting, but for a trend-reporting tool the essentials are present.

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 single window parameter is fully described in the schema with enum values, a default, and semantic guidance about shorter vs longer windows. The tool description merely lists '24h, 7d, or 30d' without adding interpretive detail beyond what the schema already provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It then lists concrete outputs—top tools, top packs, and total call volume—making the tool's scope and value immediately obvious. This also differentiates it from siblings like discover_tools by focusing on cross-agent aggregate trends rather than direct tool 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 provides explicit use cases with the 'Useful for' list, covering discovery, validation, and alignment checks. This gives clear context for when to invoke the tool. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a perfect 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?

Discloses many non-obvious behaviors beyond annotations: semantic similarity threshold (Jaccard ≥0.30), partition placeholder filter (>20% returns null), fill-check logic (realizable_edge_pp ≤ 0 means do not trade), and response structure. Provides deep visibility into internal decision rules.

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, it is structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence provides distinct, actionable information without redundancy.

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

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

With no output schema, the description compensates by detailing the response fields (opportunities[], partition_check, gap_pp, suggested_trade). It also covers filters, edge cases, and references to sibling tools for related needs. Comprehensive for a complex tool.

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

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

Schema coverage is 100% and both parameters already have strong descriptions. The tool description adds extra value with concrete slug examples, mode recommendations, and behavioral hints (e.g., topic catches cross-event patterns). Useful but not groundbreaking.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the exact detection methods and scope.

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

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

Explicitly describes three usage modes: no args for trending_scan, event for per-event partition checks, and topic for cross-event scanning. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' Clear when-to-use guidance.

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

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

Even with strong annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral disclosure: the three-segment response structure, Kelly cap at 0.25, slippage handling, the 24h-move warning, placeholder-slug filtering, per-sport bias correction constants, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). This goes far beyond what annotations provide and gives agents a thorough mental model of the tool's behavior.

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

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

The description is long but extremely information-dense and well-structured, with clear sections (model families, response structure, knobs, caching). It is front-loaded with the core purpose. While every sentence adds value, the sheer length (near 400 words) could be slightly overwhelming; a bit of tightening would push it to 5. Nevertheless, the organization makes it easy to scan.

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

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

Given the tool's complexity (9 parameters, three segments, nested response fields), the description is remarkably complete. It explains the output structure including _diagnostics, why segments may be empty, the Fed bet exclusion rationale, and even the internal logic of the concentrated_longshot gate relaxation. No output schema is needed because the description effectively documents the return shape.

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

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

Schema coverage is 100%, but the description adds meaning well beyond the schema. For example, min_partition_leg_kelly explains that partition arbs always return kelly_fraction_half=0 at the parent level and how this knob applies per-leg instead. slippage_pp details why 0.3 is the default and when to adjust it. min_liquidity clarifies that for partition_overround it applies to 'at least one top_leg.' The description enriches every parameter with context that helps an agent choose appropriate values.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on the 'what should I bet on today' use case and mentioning it avoids paging hundreds of markets.

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 for when to use the tool ('Built for "what should I bet on today"') and gives concrete guidance on knob usage (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also notes that Fed bets are excluded from ranking due to unreliable signal, adding usage nuance. However, it does not directly name alternative sibling tools for comparison, so it misses the explicit 'when not to use' aspect.

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 substantial behavioral detail beyond annotations: history limited by 60-day snapshot TTL, snapshots written only on cache-miss causing gaps, decay computed on daily closes rather than intraday, and the meaning of expired opportunities. These are all non-obvious behaviors that help an agent understand limitations.

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 clearly structured into purpose, args, response, and limits sections. Every sentence carries useful information, but it is verbose and could be tightened without losing substance.

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

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

Given no output schema, the description comprehensively explains the return format (tracked[], expired[], snapshot_dates[]) including field-level detail and edge cases. It also covers data gaps, TTL limits, and computation basis, making it fully self-contained.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a bit of extra context ('snapshot family', 'lookback') but doesn't materially go beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge listing.

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

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

Provides clear context for when to use the tool: to answer 'how long has this edge existed and is it shrinking?' and explains why that matters (fresh vs. old wide edges are different trades). It doesn't explicitly name alternative sibling tools, but the context is strong enough for an agent to infer usage.

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

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

Even with annotations already marking the tool as read-only and idempotent, the description adds significant behavioral context beyond them: it walks the ladder, returns top_of_book/vwap/slippage, can result in partial fills, and warns that partial basket fills convert an arb into an unhedged directional position. It also explains that size_usd means different things for buys vs sells and basket mode. This richly discloses behavior and risk.

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

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

The description is long but well-structured with clear 'SINGLE-MARKET:' and 'BASKET:' sections, front-loading the core purpose and requirements. Every sentence is informative and not redundant, though it does restate some schema-level parameter details, making it slightly longer than strictly necessary. Still, given the tool's complexity, it earns a 4.

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

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

The description is remarkably complete given the tool's complexity and lack of an output schema. It not only lists return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, thin_legs, etc.) but also explains their meaning in context (e.g., forced_directional_risk names legs likely to strand the user unhedged). It covers usage timing, failure modes, and the dominant loss mode, leaving no major gaps.

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

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

Schema coverage is 100% and each parameter has a detailed description. The tool description adds the critical constraint that exactly one of `market` or `event` is required (not present in schema), and clarifies how `side` and `size_usd` vary by mode. This goes beyond the schema, though the schema already carries much of the load, so a 4 is appropriate.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk, and it enumerates two distinct modes (single-market and basket) with precise output metrics.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides a rationale (theoretical overround on thin books is not capturable) and clarifies prerequisites (REQUIRES one of market or event), offering strong guidance versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the bar is lower, but the description vastly exceeds it. It discloses compatibility codes and their meanings, gross-vs-net fee handling, unclassified legs never being paired, skipped-leg counters, and the subtle meaning of null temporal_alignment. 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 but well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence carries distinct information. A short top-level when-to-use summary would improve scanability, but the density is justified for a tool with many safety codes.

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?

Since there is no output schema, the description must explain return values, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, and skipped-leg counters. It also explains per-entry flags and edge cases like null alignment, making it complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it enumerates the 10 topic shortcuts, explains that explicit parameters override the topic-mapped side, and states that both modes run the identical matcher and disclosures. This helps the agent reason about parameter interactions.

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 first sentence clearly defines the tool as a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming the specific resource and operation. It does not explicitly reference sibling tools to disambiguate, though the venue pair is distinctive.

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

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

The description explicitly explains the two invocation modes (`topic` shortcuts vs. explicit ticker/slug) and when each is appropriate, and warns that 'pre-mapped ≠ tradeable.' However, it does not compare against sibling tools or state when not to use this tool in favor of an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context beyond annotations: scoping to identifier (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (retrieve/list). No contradiction.

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

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

Three sentences, each with a distinct purpose: operation, use case, and scoping/pairing. No filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema, annotations present), the description covers operation, use case, scoping, and sibling relationships. It is complete enough 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% for the single parameter 'key', which already states 'Memory key to retrieve (omit to list all keys).' The description echoes this but does not add new parameter semantics 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 uses specific verbs and resources: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes from sibling tools by naming remember and forget as counterparts.

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

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

Explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also mentions alternatives: 'Pair with remember to save, forget to delete.'

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

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

The description discloses a state-changing operation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the readOnlyHint=true annotation, which implies no side effects. This is an annotation contradiction.

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

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

The description is compact and front-loaded, with four sentences each serving a purpose: explaining the core action, listing returned fields, describing filtering options, and covering polling behavior and an alternative endpoint. 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?

Despite lacking an output schema, the description explicitly mentions the return fields (source, citation_uri, raw payload), covers polling suitability, and cross-references an external endpoint. Combined with the fully described schema parameters, an agent has all necessary information 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%, providing a baseline of 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying the since format as ISO timestamp, and explaining mark_read's effect on subsequent calls.

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 'Pull fired events from your subscription feed,' giving a specific verb and resource. It clearly distinguishes the tool from siblings like list_subscriptions and recent_changes by focusing on alert events.

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 (for polling alerts) and mentions filters, mark_read behavior, and an alternative REST endpoint. However, it does not explicitly name alternative tools or provide exclusionary 'when not to use' guidance.

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

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

Discloses rich behavioral detail beyond the readOnly/idempotent annotations: fans out to SEC EDGAR, GDELT→GNews fallback behavior, USPTO soft-fail due to PatentsView API sunset, and the exact return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is substantial added context.

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

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

The description is front-loaded with user-intent phrases, then efficiently packs essential details—sources, fallbacks, date formats, return shape, and alternative tool—into a dense but well-organized paragraph. Every sentence earns its place; no filler or redundancy.

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

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

Given the tool's complexity (multi-source, fallback logic, date parsing, output schema absent), the description covers all critical aspects: source APIs, fallback strategy, error/soft-fail behavior, return format, and an explicit alternative. An agent can confidently decide to invoke this tool and know what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete date format examples ('7d', '30d', '3m', '1y') and a recommended default for typical monitoring, helping agents choose appropriate `since` values. It doesn't add much for `type`/`value` beyond the schema, but the extra usage guidance justifies a 4.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with explicit examples ('What's new with X') and a concrete verb phrase. It distinguishes itself from siblings by explicitly naming entity_profile as the alternative for static profiles, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance via NLP-style examples, and directly states 'Use entity_profile instead when you want the static profile... regardless of window.' It also offers practical parameter advice ('Use "30d" or "1m" for typical monitoring'), going beyond a vague 'when needed'.

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, the description adds context about key-value scoping by identifier and retention policies (persistent for authenticated users, 24 hours for anonymous). It does not contradict the idempotentHint, and while it doesn't mention overwrite semantics, the idempotent hint covers that. The added details are meaningful.

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 primary action, followed by use cases and storage details. Every sentence adds value, and it is concise enough for quick comprehension without being terse.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, when to use, key-value format, scoping, persistence, and relationships with siblings. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'key-value pair' but does not add significant detail beyond the schema's field descriptions. It doesn't explain value length limits or special encoding, so it stays at the baseline.

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

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

The description clearly states the action ('Save data') and the resource ('data the agent will need to reuse later'), with concrete examples. It distinguishes itself from sibling tools by explicitly mentioning recall and forget as paired 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?

Provides explicit 'Use when' scenarios (discovering a resolved ticker, target address, user preference, research subject) and names alternatives ('Pair with recall to retrieve later, forget to delete'). This is clear guidance on when to use vs. alternatives.

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

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

Beyond the read-only/idempotent annotations, it discloses graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity behavior (returns figi_candidates instead of asserting), explicit unresolved fields, source labelling, and internal cascading lookups. It also notes ISIN resolution reaches non-US issuers via GLEIF, which is non-obvious behavior an agent needs to trust the result.

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 core directive is front-loaded and useful, but the body is a dense, sprawling set of parentheticals and repeated caveats (e.g., the figi_candidates sentence is overly long). It is not inappropriately short, but it would benefit from tighter sentence structure and clearer separation of core behavior from edge 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?

Despite lacking an output schema, the description fully compensates by specifying what identifiers are returned for each type (CIK, ticker, company_name, LEI, FIGI; RxCUI, ingredient, brand), how unresolved identifiers are represented, and how ambiguity is surfaced. It covers failure modes, input variants, and source availability, so an agent has enough context to call and interpret the result.

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

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

Although the schema already documents both parameters at 100% coverage, the description adds critical value constraints: for company value it explains accepted inputs (ticker, CIK, ISIN, name) and for the FIGI path it instructs passing the issuer exactly as printed and warns against trailing security-class words. It also expands the type enum with the full company/drug resolution behavior and identifiers returned.

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

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

The description opens with concrete example phrasings and a clear verb-resource statement: resolve a spoken NAME to canonical identifiers that other tools require. It enumerates supported types (company, drug) and clarifies it is the first step whenever a name needs an ID, setting it apart from the sibling tools that consume identifiers or provide 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?

It explicitly routes usage with 'Use FIRST whenever you have a name but need an ID' and explains the covered entity types and input formats. It does not name alternative sibling tools or state explicit when-not-to-use conditions, so it stops short of a full 5.

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

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

The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already cover safety, and the description adds behavioral detail: it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. It also discloses that it calls ai_visibility_check internally. No contradictions with annotations. Could give more detail on rate limits or API key handling, but the essential behavior is transparent.

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

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

The description is three sentences, front-loaded with the core purpose, followed by an illustrative example and a concise return summary. Every sentence earns its place with no redundant or filler content.

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

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

For a tool with no output schema, the description sufficiently explains the return format (ranked list with score, confidence, signal density). It also handles parameter nuance (models, _apiKey) via the schema. It could be more explicit about sorting direction or edge cases, but given the moderate complexity and rich annotations, it is reasonably complete.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters. The description reinforces the meaning of 'entities' (your brand + competitors) and the purpose of 'context' (shared disambiguation), but adds little new semantic value beyond what the schema already states. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It identifies the specific verb ('compare') and resource ('AI visibility'), and distinguishes it from sibling tools like ai_visibility_check (single-entity check) by explicitly mentioning it probes multiple entities and ranks them. The example use case ('does Claude know about us as well as our competitors?') further clarifies intent.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits.' It also implies an alternative by referencing ai_visibility_check for probing individual entities. However, it does not explicitly state when NOT to use it or name alternative tools like compare_entities, though the distinction is implied.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: composite fan-out, graceful degradation of partial failures, bundlephobia's first measurement delay (5-30s), and the sources_failed field. No contradictions with annotations.

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

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

The description is dense yet compact, front-loading the core purpose and then providing use cases, output fields, and limitations in a logical order. Every sentence carries useful information without redundancy.

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

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

Despite no output schema, the description enumerates the exact summary fields returned (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), plus per-advisory detail and alternative versions. It covers ecosystem scope, performance caveats, and failure behavior, making it complete for a composite tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning: scoped packages are accepted ('@types/node') and version defaults to latest when omitted. It also clarifies the npm-only ecosystem constraint, which is not fully captured by the generic 'npm package name' schema description.

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

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

The description opens with a specific composite check: 'should I add this npm package to my project' in one call, then names the fan-out sources (deps.dev, bundlephobia). This clearly identifies the tool's verb, resource, and scope, distinguishing it from all 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?

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. No ambiguity about when to invoke this tool.

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

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

The description goes well beyond the annotations by disclosing the algorithm (BGE-base-en embeddings + cosine), the windowing approach (500-char overlapping windows), the input cap (200K chars with truncation and flagging), and the output characteristics (passages with character offsets and similarity scores). This significantly enriches the agent's understanding of how the tool behaves.

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?

Every sentence in the description earns its place. The first sentence states the core function, the second gives the use case and benefit, the third provides a pairing with an alternative tool, and the fourth discloses technical constraints. There is no redundancy or filler; the description is dense but appropriately sized.

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 adequately covers the return format by mentioning 'top-N passages with character offsets and similarity scores.' It also covers limitations (200K cap, truncation) and the intended workflow. The tool is simple enough, and the description gives all necessary context for an agent to understand its capabilities and boundaries.

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 beyond the schema: it clarifies that 'text' should be a fetched record, explains the 200K character cap and truncation behavior, and reinforces the query as a natural-language question. These additions give a better sense of how to use each parameter effectively.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination. It immediately distinguishes itself from siblings by emphasizing that the text is already fetched and the search is conducted within that text, returning passages with offsets and scores. It even names the complementary tool ask_pipeworx_grounded, making the differentiation explicit.

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

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

The description provides an explicit 'Use when' condition: 'when the record is too big to cram into the prompt.' It also supplies a clear alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both a positive trigger and a contrast with an existing tool.

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

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

The description goes well beyond annotations. It discloses account requirements (anonymous + BYO cannot persist), delivery channel specifics, SMS verification and cap, webhook HMAC signing and one-time secret, and auto-disable after 10 consecutive failures. This adds substantial behavioral context beyond readOnlyHint=false and idempotentHint=true.

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 front-loaded with the purpose and return. Every sentence carries necessary detail (types, delivery, constraints). It is relatively long but justified by the complexity of the tool. Slightly verbose, but not wasteful.

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 (nested params, multiple delivery channels, no output schema), the description is thorough. It covers account prerequisites, return value, subscription types with examples, delivery options with limits, and security details. It is effectively complete for the agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters by giving concrete examples (e.g., items:["5.02"] = officer change, params:{topic:"fed"}, series_id:"UNRATE") and clarifies return behavior ('Returns the new subscription id'), which is not in the schema. This adds meaningful 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This names the resource (subscription) and the specific action (create), and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides explicit context for when to use it: creating a monitoring subscription, with supported types like sec_8k, polymarket_edge, and fred_series. It also imposes a prerequisite ('Requires a Pipeworx OAuth account') and chain constraints (phone must be verified, 10/day cap). It does not explicitly contrast with alternatives like list_subscriptions or unsubscribe, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond this: it explains the response is 'category-bucketed example questions' drawn from the live catalog, and that each includes the exact tool and argument shape. It also notes the `topic` parameter's focusing effect.

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 thoughtfully front-loaded with natural user phrasings like 'What can I ask Pipeworx?' and 'give me ideas', then moves into a dense but well-structured explanation of behavior and use. Every sentence carries load, though the length is at the higher end; it earns a 4 rather than 5 due to slight redundancy in the category list.

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 simple one-optional-parameter schema and rich annotations, the description covers all necessary context: what the tool returns, how it can be scoped, when to use it, and how it relates to other meta-tools. Even without an output schema, the description sufficiently describes the return format and content.

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 covers the only parameter (`topic`) with a description and allowed values, so schema coverage is 100%. The description adds illustrative examples ('finance', 'pharma', 'betting') and explains that omitting `topic` gives a cross-category spread, but this goes only slightly beyond the schema's own explanation.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses a specific verb ('suggest') and resource ('what to ask Pipeworx'), and it distinguishes itself from siblings by explicitly positioning it as 'Use this FIRST' and by detailing the unique output (category-bucketed questions with tool+argument mappings).

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

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

The description provides explicit when-to-use guidance: '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 hints at alternatives by naming meta-tools like ask_pipeworx, entity_profile, and compare_entities, but it does not explicitly contrast with sibling tools such as discover_tools, so a small gap remains.

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 valuable context beyond annotations: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This aligns with the idempotent and destructive hints while giving richer operational understanding.

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

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

Two sentences, front-loaded with the action, and every sentence provides essential behavioral or contextual information. 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 single parameter, good annotation coverage, and absence of output schema, the description fully covers what the tool does, its constraints, and the post-effect. It is self-sufficient for an agent to use correctly.

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

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

The schema already fully documents the single parameter (id as a uuid returned by subscribe) with 100% coverage. The description adds no further parameter-specific semantics beyond 'by id', so it meets the baseline for high 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 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from sibling tools like subscribe and list_subscriptions. The action is unambiguous.

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

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

Provides clear context about ownership enforcement and the soft-delete behavior, and references recent_alerts for historical events. However, it does not explicitly name alternatives or state when not to use it, just implies the 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 the annotations (readOnly, openWorld, idempotent), the description discloses key behavior: the two verification pipelines, the meaning of could_not_verify vs. unsupported, the return structure (verdict, evidence, citation, reasoning), and the error field. This is rich behavioral context that helps the agent interpret results correctly.

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

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

The description is long but information-dense; every sentence serves a purpose, covering trigger phrases, routing, verdicts, and error semantics. It is well-structured but could be tightened slightly (e.g., the examples and full verdict list are somewhat redundant with the schema and output description). Still, it earns a 4 for balance.

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

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

For a complex tool with no output schema, the description compensates fully: it explains the output verdicts, the citation format, error handling, and the fact that this replaces multiple sequential calls. It gives the agent enough context to use the tool correctly without additional documentation.

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 describes both parameters (claim and tolerance_pct) with 100% coverage. The description adds value by explaining how tolerance_pct overrides claim wording and suggesting values for hallucination detection, which goes beyond the schema's literal definition.

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: natural-language claim verification against authoritative sources. It gives concrete trigger phrases and examples, and distinguishes itself from sibling tools by focusing on fact-checking with verdict outputs (confirmed, refuted, etc.) and by replacing multiple sequential calls.

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

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

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," and explains the two routing paths (company-financial vs. other claims). However, it does not explicitly mention when not to use it or name alternative sibling tools, 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.