npm

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: the default model (Workers AI Llama-3.3-70b), the BYO Anthropic key with direct cost implication, and the per-model return structure. This is strong additional transparency.

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

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

Three sentences, front-loaded with the core action, then optional key/cost, then return shape and use cases. No filler; every sentence earns its place.

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

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

Despite lacking an output schema, the description explicitly describes the return contract (per-model {score, confidence, signals, raw_response} + combined view), the default model behavior, optional key handling, and representative use cases. This is adequately complete for a 4-parameter tool with strong annotations.

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 already has a thorough description. The description adds meaning by noting that the default model is free and that passing `_apiKey` means you pay Anthropic directly, which clarifies real-world implications not in the schema.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly distinguishes this from sibling tools like ask_pipeworx by emphasizing scoring visibility per model rather than general question-answering.

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 supplies clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternative tools or state when not to use it, but the context is specific enough to guide an agent.

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

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

Annotations already establish the read-only, idempotent, open-world safety profile. The description adds meaningful behavioral detail: it auto-selects among 5,798 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It stops short of covering rate limits or failure modes, but those are secondary given the read-only annotation.

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

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

The description is front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), then moves through domains, mechanism, trigger phrases, examples, and sibling pointers. Every sentence contributes distinct information, and the structure allows an agent to quickly decide whether to invoke this tool.

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

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

For a high-complexity router with no output schema, the description is unusually complete: it defines the input, the routing behavior, the citation-URI return characteristic, and the main alternatives. It does not enumerate a full response schema, but the note about structured answers and citations is sufficient for an agent to 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?

The schema already documents all six parameters, including aliases, at 100% coverage, so the baseline is a 3. The description adds value by giving concrete accepted query phrasings and six domain examples, reinforcing that the single required parameter is a natural-language question.

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

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

Clearly identifies ask_pipeworx as the high-level router for factual, current, and historical data queries, stating that it routes to thousands of tools and returns citation-backed structured answers. The explicit 'PREFER OVER WEB SEARCH' plus the enumerated domain list make its purpose easy to distinguish from general web-search tools and from 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?

Gives explicit trigger phrases, domains, and a default directive ('START HERE for most questions'), and it explicitly says to prefer this over web search. It also names sibling alternatives at the end, but does not define the conditions that would make ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, or bet_research the better choice, so the routing guidance is not fully complete.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that candidate routing improvements may be live, that no candidate is currently active, and that the tool currently matches ask_pipeworx exactly. It also clarifies that this is a full working router rather than a degraded fallback, which is valuable behavioral context.

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

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

The description is a bit wordy with five sentences, but each sentence carries useful information: identity, current experimental status, usage guidance, and a clarifying note that it is fully functional. It is front-loaded with the key beta/identical nature and avoids unnecessary fluff.

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

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

Given no output schema, the description usefully mentions the same response shape as ask_pipeworx and clarifies current behavior and experimental status. It sufficiently covers how to invoke the tool and what to expect, though concrete response details are not spelled out beyond referencing the stable sibling.

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 all parameters and aliases. The description adds only a generic reference to 'same arguments' and does not provide additional parameter-level semantics or examples beyond what the schema already states.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing candidate routing improvements. This makes the tool's purpose and relationship to siblings immediately understandable.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router. It provides clear context about current behavior and experimental status, though it does not explicitly say when not to use it in favor of the stable 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?

The description goes well beyond the annotations by detailing exact success and refusal return shapes, including the refusal_reason enum values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It discloses the extra LLM call cost and the grounded extraction constraint. No contradictions with annotations; the readOnlyHint is consistent with a read-only grounded answer mode.

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: it defines the behavior, the routing, the return contract, the refusal contract, the appropriate use cases, and the cost tradeoff. It is front-loaded with the most important purpose and ends with actionable guidance. No filler or repetition of schema 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 and non-trivial refusal behavior, the description is unusually complete. It explains what the agent should expect on success, what refusal reasons exist, when to prefer the grounded mode, and why it costs more. An agent has all the context needed to invoke this tool correctly and interpret its results.

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

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

Schema description coverage is 100% and the only meaningful parameter, 'question', is fully documented with a clear description and alias list. The tool description adds no extra parameter-level detail, so the baseline of 3 applies: the schema already does the heavy lifting and the description does not need to compensate.

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, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly names the sibling it overlaps with (ask_pipeworx), states that it routes the same way, and explains the defining difference: it extracts answers only from tool results. An agent can immediately distinguish this from ask_pipeworx and ask_pipeworx_beta without inspecting schemas.

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 is explicit about when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative for casual cases: 'prefer ask_pipeworx for casual lookups,' and gives a concrete reason (extra LLM call cost). This is strong selection guidance with both inclusion and exclusion criteria.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses the resolver contract (market_match_confidence, scores, alternatives), safety mechanisms (low-confidence short-circuit, blocking on closed/dead markets), wide-spread illiquidity warnings, news fallback behavior (429 handling), and resolution-rule risk (cancellation/void settlement). This is exemplary behavioral disclosure.

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 uppercase section labels, examples, and a logical flow from purpose to fan-out to response shapes to safety. It front-loads the core purpose and use cases, then adds necessary behavioral detail. While not terse, every section adds value and the structure makes it scannable.

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

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

Despite having no output schema, the description thoroughly explains all relevant response fields: result.market, result.analysis, result.evidence, result.parent_event, news fields, status values, and tradeability warnings. It also covers edge cases like low-confidence matches, closed markets, and cancellation rules. For a complex tool, the description is remarkably complete.

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

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

The input schema has 100% coverage for all three parameters, including descriptions for 'market', 'depth', and 'include_raw'. The description reinforces the market parameter with examples but adds no new semantic detail beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by stating its use case ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailing the fan-out to category-specific data packs. The purpose is unmistakable and unique among the sibling list.

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 via the 'Use for...' phrase and numerous examples. However, it does not name specific alternative tools or give when-not-to-use conditions, which prevents a 5. The guidance is still clear and actionable.

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

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

Annotations already declare read-only/idempotent behavior, but the description adds substantial context: it discloses data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years correctly, states results are sorted by primary metric, and mentions return of paired data with citation URIs. This goes well beyond the annotations.

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

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

The description is dense and well-structured, front-loaded with trigger phrases and the key 'ALWAYS PREFER' guidance. While every sentence adds value, it is longer than strictly necessary, and the 'Replaces 8–15 sequential lookups' is a value prop rather than essential behavioral info.

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 adequately explains the return structure ('paired data + pipeworx:// citation URIs'), sorting behavior, and the types of data retrieved for each entity type. It also covers quirks (off-calendar fiscal years) and performance benefits, making it complete for selection and 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?

Even with 100% schema coverage, the description enriches both parameters: it explains what 'type=company' vs 'type=drug' means in terms of data fields, and gives concrete examples for the 'values' array (tickers/CIKs, drug names). This adds meaning beyond the schema.

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

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

The description opens with concrete user query patterns ("Compare X and Y", "X vs Y", "which is bigger") and clearly states the tool performs side-by-side comparison of 2–5 entities. It distinguishes itself from sibling tools by explicitly preferring it over 'sequential single-pack lookups'.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive and an alternative to avoid. It also details exactly what each entity type (company vs drug) pulls, guiding usage.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: parallel decomposition, gap[] reporting, never-invented results, contradiction scans, hop field, citation_uri resolvability, semantic excerpting, and expected latency per depth. 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 information-dense and front-loaded with the account requirement and alternative tool. Most sentences add unique value; minor repetition around depth behavior keeps it from 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?

For a complex research orchestration tool with no output schema, the description is exceptionally complete: it covers authentication, alternatives, scope, process, return packet contents, gaps, contradictions, citation semantics, excerpting, and latency. An agent has enough to select and invoke it correctly.

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

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

Schema already describes both parameters at 100% coverage. The description adds meaningful depth-variant behavior beyond the enum: standard performs gap recovery, thorough chases leads and adds contradiction scanning, and thorough requires a paid plan. This goes beyond the schema but is somewhat lengthy.

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

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

Description states a specific verb and resource: it decomposes a question into facets, routes them across 5,798 tools, and returns a findings packet with citations and gaps. It explicitly distinguishes itself from open-web search and names the sibling ask_pipeworx for single lookups, so an agent can differentiate it without opening schemas.

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: best for broad/multi-part questions over structured data, with concrete examples. Also gives exclusion criteria: use ask_pipeworx for a single lookup or when not signed in. The account requirement and paid thorough tier are stated up front.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail: it returns top-N tools with names, descriptions, and full schemas, and is ready to call directly without a second schema lookup. This describes output format and efficiency without contradicting annotations.

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

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

The description is well-structured and front-loaded with purpose. The list of data domains is long but informative, showing the scope of discoverable topics. Every sentence contributes; the trade-off between length and utility is acceptable.

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

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

With no output schema, the description compensates by explaining return contents and direct-callability. It covers what it returns (names, descriptions, schemas), the limit behavior, and mentions curated examples. Combined with annotations for safety, this is fairly complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'top-N' which hints at the limit parameter, but the query semantics are already fully described in the schema (natural language description, aliases). No additional parameter meaning is added 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 starts with a specific verb+resource pairing: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by positioning as a meta-tool for discovery ('Call this FIRST when you have many tools available'), not as a direct data/research tool like deep_research or search_packages.

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 context is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... not just one answer.' This gives clear when-to-use, though it does not explicitly name alternative tools or state when not to use it beyond the 'not just one answer' qualifier.

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

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

Annotations already declare readOnly/idempotent/openWorld/destructive=false, and the description adds substantial behavioral context: it fans out across specific sources, soft-fails USPTO PatentsView after May 2025, treats empty FDA-licensed biologics as expected for small-molecule companies, and reports per-source success/failure via sources_used/sources_failed. It also specifies the private-company resolved:false behavior rather than a bare failure. 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 every segment earns its place given the multi-source fan-out and failure-mode details. It is front-loaded with examples and the preference directive before enumerating return sections. Slight redundancy with the schema on type/value interchangeability keeps it from 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?

With no output schema, the description carries the burden of explaining return shapes, and it does so thoroughly: it enumerates each result section (filings with pipeworx URIs, fundamentals sorted by period_end, patents, contracts, FDA products, hiring, news, LEI) plus sources_used/sources_failed. It covers resolution failure for private companies, so nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100% (both type and value have descriptions, type has an enum). The description adds extra nuance beyond the schema: value may be a ticker, zero-padded CIK, or company name with EDGAR name resolution, and type values are interchangeable. This is useful but marginal on top of already-documented schema.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme') and states the core action: produce a full cross-source profile of a US public company in one parallel call. It explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, so an agent can differentiate it from related research 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?

It contains an explicit directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This states the triggering user intent and the alternative pattern to avoid, which is strong 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?

Annotations already declare destructiveHint and idempotentHint; description adds context by identifying the resource ('previously stored memory') and use case ('clear sensitive data'). No contradictory or missing critical behavioral info beyond annotations.

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

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

Two sentences, action first, then usage guidance and sibling references. Every sentence earns its place.

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

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

Tool has only one parameter, no output schema, and annotations cover destructive/idempotent behavior. Description gives purpose, when-to-use, and sibling pairing — sufficient for a simple tool.

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

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

Schema description covers 100% of the parameter ('Memory key to delete'). The description adds no additional parameter details beyond saying 'by key', so baseline 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?

Description states 'Delete a previously stored memory by key' — a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by implying store/retrieve vs delete.

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

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

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

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 openWorldHint=true, but the description adds specifics: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a 'single text blob ready to drop at site-root/llms.txt'. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core action and output, followed by a concise 'Useful for' list. Every sentence earns its place with no wasted words or redundancy.

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

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

For a tool with two parameters and no output schema, the description sufficiently explains the output format and use cases. It lacks detail on edge cases like handling of inaccessible URLs or JavaScript-heavy sites, but given the simplicity, it is 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 description coverage is 100%, so the baseline is 3. The description mentions 'any URL' and 'key links' which loosely relates to 'url' and 'max_links', but does not add meaningful parameter semantics beyond what the schema already provides.

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

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

The description clearly states it 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. It distinguishes itself from siblings by focusing on creating the llms.txt file, not just auditing or checking AI presence.

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

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

The 'Useful for' section provides explicit use cases: indexing a client's site, drafting llms.txt for a project, or auditing competitor AI crawler view. It gives clear context for when to use the tool, though it does not explicitly name alternative tools or exclusions.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the safety profile is known. The description adds behavioral context by specifying the return values (total downloads, start date, end date) and accepted period formats, though it also introduces 'last-year' which is not present in the schema, creating a minor 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?

Two sentences, front-loaded with the action and object. Every word earns its place, includes examples, and is 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 simple read-only nature and presence of an output schema, the description is mostly complete. It covers return values and period formats. However, the 'last-year' discrepancy with the schema and lack of mention of the default period (which the schema does state) slightly reduces completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely repeats the schema's period list and adds 'last-year' which is not in the schema, potentially confusing. No significant new semantic meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Fetch') and resource ('npm download counts for a package') and clarifies scope with period types. This clearly distinguishes it from siblings like get_package or get_version_info which deal with other package data.

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

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

The description implies usage when you need npm download counts, but it does not explicitly state when to use this versus alternatives, nor does it mention any exclusions or alternative tools. The purpose is clear enough that an agent can infer, but explicit guidance is absent.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description need not restate that. It adds the set of returned fields, which gives some context about behavior, but does not disclose potential edge cases (e.g., behavior for non-existent packages) or limitations beyond the schema's note about exact name. This is adequate but not richly 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 two sentences: the first states the tool's action and output fields, the second gives usage positioning. It is front-loaded and every sentence earns its place. 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 well-documented parameter, strong annotations, and an output schema, the description provides the necessary context: what the tool does, which fields to expect, and when to use it. There are no critical gaps that would prevent 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?

The sole parameter 'name' is fully described in the schema with an exact example and clarification ('Exact package name'). Schema coverage is 100%, so the description does not need to add parameter details. The description's mention of 'specific package' aligns with the schema but adds no new 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 clearly states the tool's purpose: 'Get full details for a specific package' and enumerates the exact fields returned (version, description, dependencies, homepage, repository, license). It distinguishes from sibling tools like search_packages and list_versions by focusing on a single package's detailed metadata and explicitly referencing the search-then-evaluate workflow.

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

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

The description provides explicit usage guidance: 'Use after search_packages to evaluate a candidate package.' This tells the agent when to use this tool in a multi-step workflow, implying that it is not for discovery or broad queries. It clearly positions the tool relative to an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by enumerating the specific metadata fields returned (e.g., integrity hash, unpacked size, deprecation notice) and explaining version resolution semantics (exact version, dist-tag, or omit for latest). 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 and front-loaded: the first sentence states the purpose and output fields, the second sentence provides usage guidance and version syntax. Every sentence is informative, with 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 two parameters and no output schema, the description is highly complete. It covers what the tool returns, common use cases, and version format options. The annotations cover safety/behavioral traits, and the sibling context shows clear differentiation from similar npm tools.

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 fully documents both parameters. The description largely repeats the version parameter semantics already present in the schema, adding only the contextual phrase about "dependencies of <pkg>@<version>". This provides marginal value beyond the schema but does not meaningfully compensate for any gap.

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: obtaining metadata for a specific version or dist-tag of an npm package, listing the exact fields returned (dependencies, engines, license, tarball hash, etc.). It distinguishes itself from siblings like get_package and list_versions by focusing on a specific version rather than a package's general info or available versions.

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

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

The description provides explicit use cases: "dependencies of <pkg>@<version>", pinned-version audits, and inspecting a particular release. It does not explicitly name alternative tools or state when not to use it, but the use cases are clear and contextualized within the sibling tool set.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the default filtering of inactive subscriptions and specifies the return fields, which is useful context beyond annotations since no output schema exists. However, it does not mention pagination or potential large result sizes.

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

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

Two sentences with no filler. The first sentence states the action and output; the second provides actionable use cases. Every word earns its place, and the structure is front-loaded with the core purpose.

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

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

For a simple list tool with one optional parameter, the description is complete: it names the tool's function, lists the return fields to compensate for the missing output schema, and gives usage context. Combined with strong annotations, this is sufficient for an agent to invoke it correctly.

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

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

The schema covers 100% of the parameters with a clear description for include_inactive. The description does not need to repeat this, and the active-subscription context already hints at the default behavior. The baseline of 3 is appropriate because the schema handles the semantic burden.

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

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

The description uses a specific verb 'List' and a clear resource 'the caller's active subscriptions'. It distinguishes itself from siblings like subscribe/unsubscribe by focusing on enumeration rather than creation or cancellation, and it explicitly lists the returned fields.

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 provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to use this tool versus adding or removing subscriptions, covering both pre-add and pre-cancel scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral details beyond annotations: versions are returned newest-first, and it includes package created/last-modified timestamps, which is not present in the schema or annotations.

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

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

The description is two sentences, front-loaded with the core action, and uses a parenthetical to list user questions without bloat. Every sentence contributes meaning, and there is no redundant restating of the tool name or schema.

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 2-parameter tool with strong annotations and 100% schema coverage, the description is fully adequate. It explains what the tool returns, the ordering, and its intended use cases. No output schema is present, but the description already mentions the key output elements (versions, dates, dist-tags, deprecation notices, timestamps), so nothing 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?

The input schema has 100% description coverage: name is described as an exact package name with examples, and limit has a clear default and max. The description adds no further parameter semantics, 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 uses a specific verb and resource ('List published versions of an npm package') and clearly states the delivered fields (publish dates, dist-tags, deprecation notices). It also names the exact user questions it answers, which effectively distinguishes it from siblings like get_version_info or get_package.

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

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

The description gives clear usage context by listing the questions the tool answers ('what versions exist', 'when was last published', 'is latest deprecated'). It does not explicitly name alternative tools or when not to use it, but the provided use cases are sufficient for an agent to select it appropriately.

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

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

Annotations are all false (not read-only, not destructive), but the description adds critical context: rate limit of 5 per identifier per day, no quota count, and the claim_token mechanism for tracking feedback without an account. It also discloses how to later retrieve fix status with the token, going well beyond 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?

The description is a single dense paragraph but every sentence adds needed detail (scope, token, rate limit, roadmap). It is front-loaded with purpose and uses clear punctuation. Slightly long but justified given 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?

Despite no output schema, the description explains the expected return (claim_token) and the workflow for submitting and following up. Together with 100% schema coverage, this is fully sufficient 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 baseline 3. The description adds value by giving a concrete usage pattern for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})') and instructing to describe issues in terms of tools/packs, not paste user prompts. This supplements the schema descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist', using a specific verb and resource. It explicitly differentiates from sibling tools by scoping feedback to Pipeworx connection tools only, and the title 'Send Pipeworx Feedback' reinforces the purpose.

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

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

Provides explicit triggers: bug, feature/data_gap, praise. Also includes an exclusion: 'if the tool came from a different MCP server... file it with that server instead' and a heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary 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?

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count).' It also discloses caching behavior ('Cached 5min-1h depending on window'), which is useful for freshness expectations.

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

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

The description is dense but well-structured, with a lead sentence for purpose, a returns statement, a numbered list of use cases, and two sentences on data origin/privacy and caching. Every sentence provides distinct value with no redundancy.

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

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

For a simple one-parameter read-only tool with no output schema, the description covers the return shape ('top tools, top packs, total call volume', '(pack, tool, count)'), the time windows, use cases, data source, privacy, and caching. This is sufficiently complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with the single 'window' parameter fully described in the schema (enum values and semantics). The description reiterates the window options but adds no new parameter meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's function with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which handle queries or discovery rather than aggregate trending signals.

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: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice', and 'seeing whether your use case aligns with what most agents need.' It lacks explicit exclusion or alternative tool references, so it does not fully meet the 'when-not/alternatives' bar, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavior beyond that: partition-sum deviations >3pp emit signals, placeholders like 'will-person-X' are filtered, Jaccard similarity ≥0.30 prevents bad cross-event pairing, and fill checks price against live CLOB depth. It even discloses failure modes like skipped_low_similarity and thin_legs[]. 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 quite long, but it is structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every segment adds a necessary constraint or behavior. It is front-loaded with the core purpose, but the length is still substantial for a tool with only two parameters. A 4 reflects that it earns its length yet could be tightened.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers input modes, expected output shape (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check fields), edge cases (placeholder slu, threshold limits), and how to follow up with polymarket_fill_risk. The agent has enough to invoke and interpret results 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% (both event and topic are documented), but the description goes far beyond the schema with concrete slug examples ('fed-decision-may-2026'), mode-specific semantics (event walks child markets, topic flattens related events), and how the two modes differ. It also explains what happens in each mode (partition_check in event mode, cross-event comparator in topic mode), adding meaning that the bare schema lacks.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' — a specific verb+resource+mechanism. It clearly distinguishes from sibling tools like polymarket_edges by naming the unique detection method, so an agent can immediately understand this is the arbitrage-detection tool.

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

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

Explicit when-to-use guidance is provided: 'event (recommended for a specific market)' versus 'topic (for cross-event scanning)', with a concrete example of what each mode covers. It also points to an alternative tool ('For custom sizing use polymarket_fill_risk') and warns when not to trade ('realizable_edge_pp ≤ 0 … do not trade it'). This gives clear decision rules beyond generic 'use for arbitrage'.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral details: 'Cached 1h at the KV level keyed on all knobs,' diagnostics like '_diagnostics{concentrated_longshot:{...funnel counters},category_counts,filter_skips},' and a '24h-move warning' when the market move exceeds the edge. It also reveals that Fed bets are excluded from ranking due to unreliable signals, which is non-obvious and valuable for the agent.

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

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

The description is lengthy and dense, but it is well-structured: it starts with the purpose, categorizes model families, describes the response structure, then details knobs and diagnostics. Given the absence of an output schema, explaining the response segments and fields is necessary. While some details like specific α values (tennis 1.02) could be trimmed, the overall organization earns a 4 rather than a 3.

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

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

With no output schema, the description must explain the return values, and it does: 'RESPONSE TOP-LEVEL: by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note ... and _diagnostics.' It also covers edge fields (edge_pp_net, kelly_fraction, market.liquidity) and behavior (caching, warnings, filters), making it complete for a complex tool with nine parameters.

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

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

The input schema already has 100% coverage with descriptions, so the baseline is 3. The tool description adds value by explaining the purpose and interaction of knobs, e.g., 'Tradeable-edge filter. Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven' for min_liquidity, and clarifying that min_partition_leg_kelly 'applies to the per-leg Kelly inside top_legs instead' of the parent level. This contextual guidance goes beyond the schema descriptions.

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

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

The description states a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly defines the tool's purpose and differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement. The phrase 'Built for "what should I bet on today"' further clarifies the intended use.

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 usage context: 'agents discover opportunities without paging hundreds of markets.' It explains when to use the tool (for discovering betting opportunities) and gives guidance on adjusting knobs (e.g., 'Set to 2 to require tight books'). However, it does not explicitly compare to alternative tools or state when not to use it, so it stops short of a 5.

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

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

Adds substantial behavioral detail beyond annotations: 60-day snapshot TTL, history starts when snapshotting was enabled, snapshots written only on cache-miss (gaps = no scan), decay computed from daily closes not intraday, and signed edge_pp_net (negative = SELL YES). Annotations are readOnly/openWorld/idempotent and the description complements them without contradiction.

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

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

The description is long, but every paragraph earns its place: purpose, args, response fields with meanings, and limitations are clearly sectioned (Args, RESPONSE, LIMITS). Front-loaded with the core purpose, no filler, and the structure improves scannability without losing precision.

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 read-only telemetry tool with no output schema, the description fully explains the return structures (tracked, expired, snapshot_dates), their semantics, and edge cases like gaps, TTL, and sign conventions. Parameter coverage is complete via schema, making the tool ready for correct invocation and result 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 coverage is 100%, so baseline is 3. The description goes beyond the schema by introducing 'snapshot family' semantics for window and clarifying days as lookback with a max of 30. It also ties window into the RESPONSE structure, adding context the schema alone does not provide.

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

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

States specific verb+resource: 'Edge persistence and decay telemetry' and answers the concrete question 'how long has this edge existed and is it shrinking?'. Clearly distinguishes from sibling 'polymarket_edges' by focusing on time-series persistence rather than current edge detection.

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?

Implies when to use via the example that a fresh wide edge and a 3-week-old wide edge are different trades, and mentions the 'competition clock' of median lifespan. However, it does not explicitly name alternatives or exclusion criteria, though the niche is clear from the purpose and 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, destructiveHint=false. The description adds substantial behavioral context: it walks the order-book ladder, interprets size_usd differently per mode, returns specific metrics (top_of_book, vwap_fill_price, capture_ratio, etc.), and names forced_directional_risk as a specific output. 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, the description is tightly packed and front-loaded with the core purpose. It uses clear mode separators (SINGLE-MARKET / BASKET), every sentence earns its place, and it avoids redundant phrasing. The detail is justified by the tool's two-mode complexity and absence of an output schema.

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

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

With no output schema, the description fully enumerates return fields for both modes, explains the risk model, and provides usage context. It lists all relevant outputs (e.g., verdict, thin_legs[], max_clean_notional_usd) and addresses failure modes (partial fills, stranded positions). For a complex tool, this is exemplary completeness.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains side auto mode ('auto — sell if partition sum > 1, buy if < 1'), interprets size_usd as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional S (shares per leg; each share pays $1)' for basket mode, and clarifies the clamp range. This goes well beyond the schema's basic descriptions.

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

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

The first sentence clearly states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by explicitly positioning it as a pre-trade risk check before executing those strategies.

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 direction is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the why (partial basket fills create unhedged directional risk) and distinguishes single-market vs basket modes, including input requirements and default behaviors.

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 non-destructive behavior, but the description goes far beyond them. It discloses matching caveats, compatibility_codes semantics, temporal_alignment null meaning, Kalshi fee treatment, unclassified legs never being paired, and skipped comparison counters. This is rich behavioral context well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and uses labeled sections such as TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. It is long, but nearly every sentence contributes a distinct caveat or clarification. Minor redundancy, such as repeatedly reinforcing that warnings can accompany returned pairs, prevents 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?

Despite having no output schema, the description enumerates the important response fields and their meanings: top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, and skipped counters. It also explains failure modes, per-entry flags, and when results should be treated with suspicion. This is a complete operational picture for an agent invoking 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 already describes all three parameters at 100% coverage, so the baseline is 3. The description adds real value by explaining that explicit ticker/slug values override the topic-mapped side and that both modes run the identical token-overlap matcher. It also resolves ambiguity around the topic shortcut list and how the two parameters interact.

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 names a specific verb and resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question. The description clearly distinguishes this from siblings like polymarket_arbitrage by specifying the two venues and the comparison output. The TWO MODES are also clearly labeled and explained, leaving no ambiguity about what the tool does.

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

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

The description explicitly defines TWO MODES and gives the condition for each: topic shortcuts for 10 pre-mapped macros versus explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics return compatibility_warning and that pre-mapped does not mean tradeable. It does not name sibling alternatives, but it gives strong contextual guidance on when this tool is appropriate.

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 and idempotentHint; description adds scoping to agent identifier (anonymous IP, BYO key hash, account ID) and the behavior of listing all keys when argument omitted. No contradiction.

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

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

Three sentences, front-loaded with the core action; each sentence adds necessary context (usage, scoping, pairing with siblings).

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

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

Tool is simple, output schema absent but not needed; description covers core behavior, scoping, and relationship to siblings, sufficient for an agent to invoke correctly.

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

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

Schema documents the single key parameter with 100% coverage, including the omit-to-list-all behavior. Description adds no further parameter detail beyond what schema provides, so baseline 3.

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

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

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly contrasts with sibling tools (remember, forget), making it clearly distinct.

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?

Clearly states when to use (look up context stored earlier) and explicitly names alternatives (remember to save, forget to delete), plus contrasts with re-deriving from scratch.

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 state readOnlyHint: true, implying no state changes, but the description explicitly describes a mutating behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the read-only annotation, making the tool's side effects unclear and potentially misleading for agents relying on the read-only hint.

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 of dense, relevant information: purpose, return contents, filtering, mark_read behavior, polling suitability, and an alternative REST endpoint. No wasted words, front-loaded with the action verb, and every sentence contributes to understanding the tool.

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

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

For a tool with 5 optional parameters and no output schema, the description covers the key behaviors: return fields, filtering, mark_read side effect, and polling. It lacks details on pagination and handling of unread_only, but the schema covers these. The main completeness gap is the unresolved contradiction regarding read-only vs. read-write behavior, which affects trust in the description.

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 all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds valuable semantics beyond the schema: provides an example type ('sec_8k'), clarifies that 'since' uses an ISO timestamp, and explains the state-changing effect of mark_read. This extra context helps the agent select and use parameters correctly.

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: 'Pull fired events from your subscription feed.' It specifies the return content (source, citation_uri, raw event payload) and differentiates from sibling tools like list_subscriptions and subscribe by focusing on retrieving alert events rather than managing subscriptions.

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

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

The description provides clear usage context: filtering by type and since, using mark_read, and confirming that polling works. It also offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly state when to prefer this tool over sibling tools for alert-related tasks, though the name and description make this self-evident.

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

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

Annotations already mark the tool as read-only and idempotent, but the description goes far beyond: it reveals fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx conditions, USPTO PatentsView sunset soft-fail, and the return structure with citation URIs. 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?

Although longer than average, every sentence carries valuable information—sources, fallback behavior, soft-fail details, and output format. It front-loads the purpose with relatable natural-language examples and has 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?

With no output schema, the description responsibly explains the return value (structured changes[] grouped by source, total_changes, pipeworx:// URIs). It also covers edge cases (API sunset, fallback conditions) and the alternative tool, making it complete 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?

The input schema already covers all three params at 100%, including the since format and value type. The description repeats and lightly reinforces with examples ('AAPL', '0000320193') but adds no meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description explicitly states this is a 'change feed for a company in the last N days/weeks/months', with specific verbs like 'what's new' and 'updates on'. It clearly distinguishes itself from siblings by naming entity_profile as the static-profile alternative.

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

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

Provides natural-language trigger examples and explicit guidance: 'Use entity_profile instead when you want the static profile...' This clearly communicates when to use this tool versus 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?

Beyond annotations, the description discloses scoping ('scoped by your identifier') and persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It also explains the write nature and storage format, adding significant value beyond the readOnlyHint/idempotentHint annotations. No contradiction found.

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

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

The description is five well-structured sentences, each serving a purpose: main action, usage guidance, storage mechanism, persistence behavior, and companion tools. It is front-loaded with the primary function and wastes no words.

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

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

For a simple write operation with two parameters and no output schema, the description fully covers purpose, usage, storage semantics, persistence, and tool integration. The annotations already address safety (non-destructive, idempotent), so the description is complete enough for an agent to select and invoke correctly.

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

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

The schema already has clear descriptions for both parameters with examples. The description adds extra semantic value by mentioning key-value scoping by identifier, and provides additional examples of keys/values (resolved ticker, target address). This goes slightly beyond the schema's coverage, 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 begins with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from siblings by mentioning complementary tools (recall, forget) and explains the key-value storage model. The purpose is unambiguous and covers cross-session persistence.

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 states when to use: 'Use when you discover something worth carrying forward...' and provides concrete examples. It also ties to alternatives by saying 'Pair with recall to retrieve later, forget to delete,' giving clear usage context and tool relationships.

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

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

The annotations already cover read-only, idempotent, open-world, and non-destructive traits, so the bar shifts to extra behavioral context. The description adds substantial behavior: internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-name handling via figi_candidates, explicit unresolved fields, and source labelling of every identifier. This goes far beyond the structured annotations.

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

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

The text is dense and heavily parenthetical, but nearly every sentence contributes operational guidance. It front-loads the most common use-case pattern and iterates from main purpose to type specifics to failure behavior. A bit of pruning and structural formatting would improve readability, but the length is largely justified by the multi-endpoint complexity.

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

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

With no output schema, the description must convey what callers receive and how edge cases behave. It does: canonical identifiers per type, source labels, figi_candidates for ambiguous instrument matches, unresolved entries, the ISIN-to-LEI fallback path, and enrichment degradation behavior. An agent has enough context to invoke the tool correctly and interpret unusual results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuinely useful disambiguation beyond the schema, especially the 'ENTITY NAME ONLY' rule, the bond-issuer caveat, and the note that trailing security-class words will fail FIGI matching. It reinforces ticker/CIK/name input forms with examples, making parameter usage significantly safer.

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 user utterances ('What's the ticker for…', 'find the CIK for…'), then states the specific job: resolve a user-spoken name to canonical identifiers other tools require as inputs. It further enumerates supported types and identifier sources, making the tool's purpose unmistakable and distinct from generic lookup tools.

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

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

The description gives an explicit trigger rule — 'Use FIRST whenever you have a name but need an ID' — and provides type-specific guidance including input forms and a sharp caveat about passing only the issuer name for bonds. It does not explicitly contrast itself with sibling entity tools such as entity_profile or compare_entities, so a small gap remains in 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?

With annotations already confirming read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral detail: it explains that the tool calls ai_visibility_check per entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and clarifies the operational mechanism and 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 two sentences, efficiently front-loaded with the core action, and every clause contributes meaningful information (mechanism, ranking, use case, output). 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?

The description fully covers the tool's behavior, use case, and output structure. With schema providing parameter details and annotations covering safety, nothing critical is missing. It even explains why the tool is useful (competitive audits) and how it leverages ai_visibility_check.

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

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

The schema already covers all four parameters, so the baseline is 3. The description adds extra semantics by clarifying that the first entity is treated as the 'subject' for narrative while the rest are competitors, which is not in the schema. This additional context justifies a 4.

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

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

The description clearly states the tool's function: "Compare AI visibility across multiple entities side-by-side." It also specifies the mechanism (probes each entity with ai_visibility_check), the ranking behavior, and what it surfaces (most/least recognized), distinguishing it from the single-entity sibling tool ai_visibility_check.

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

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

The description gives an explicit use case for competitive AI-marketing audits and even provides an example question. It implicitly differentiates from single-entity tools by mentioning multiple entities, but it does not explicitly state when not to use this tool or name alternative tools (e.g., compare_entities for generic comparison), so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses valuable behavioral traits: it fans out across two services, handles partial failures gracefully, mentions possible 5-30s delay on first bundlephobia measurement, and explains the 'sources_failed' field. 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 yet information-dense, front-loaded with the core purpose, followed by usage, return block, limitations, and failure behavior. Every sentence adds unique value; 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?

Given the complexity of a composite tool (two external services) and lack of output schema, the description is remarkably complete. It explains the return payload (summary fields, per-advisory details, links, alternatives), ecosystem limitation, and graceful degradation. No important behavioral or output aspect is left unaddressed.

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

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

Schema already covers both parameters (package, version) at 100%, so baseline is 3. The description adds meaningful constraint context: 'NPM ecosystem only in v1' clarifies the valid values for 'package' and indicates when not to use this tool. It also describes the output structure, aiding parameter interpretation.

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

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

The description clearly states this is a 'Composite ... check in ONE call' for npm packages, with specific verb ('scan') and resource ('dependency'). It distinguishes itself from siblings by explicitly listing the data sources (deps.dev, bundlephobia) and the types of questions it answers ('is X safe / popular / small').

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 an agent asks ...' and gives specific example queries. It also provides a when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding agents to alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the return field list, which is useful but not deeply behavioral. It does not disclose pagination, rate limits, or edge cases.

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

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

Two concise sentences with all necessary information, front-loaded with the action. There is no redundant or filler content.

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

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

Simple 2-param search tool with an output schema and strong annotations. The description covers what, when, and return content; nothing critical 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 coverage is 100% with both parameters having descriptions. The description adds no parameter-specific detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it searches npm for packages by keyword and lists the returned fields. It does not explicitly contrast with sibling tools like get_package, but the search/retrieval distinction is implicit.

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 phrase 'Use when discovering libraries for a task' provides clear context for when to use this tool versus alternatives. It does not mention exclusions or name specific alternative tools, so it earns a 4 rather than 5.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description discloses specific behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging, and returns character offsets and similarity scores. 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 three dense sentences, each adding value: purpose, usage guidelines, and technical behavior. It is front-loaded with the core function and every sentence earns its place without extraneous fluff or 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?

With no output schema, the description explains return format (passages with offsets and similarity scores) and caveats (truncation, char cap). It also covers the tool's role in a RAG-like flow, making it complete for an agent to understand expectations despite missing an output schema.

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

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

The input schema covers all three parameters (text, query, limit) with descriptive text (100% coverage), so baseline is 3. The description adds further meaning by providing examples of 'text' (SEC 10-K, article) and clarifying the purpose of 'limit' as top-N passages, which enriches understanding 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 performs semantic search inside a fetched record, returning passages with offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded and search_packages by specifying the input is already-pulled text, making the purpose specific and unambiguous.

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

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

Explicitly states when to use it: 'when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding over relevant passages. This provides clear context for use vs. alternatives, meeting the criteria for explicit when/when-not guidance.

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

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

The description adds significant behavioral context beyond annotations: it states that an OAuth account is required, returns the new subscription id, details delivery channels (feed always on, email/sms optional with caps and verification requirements), and even notes the phone number must be verified with a 10/day SMS cap. No contradiction with annotations is present.

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

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

The description is dense but well-structured: it front-loads the purpose, then provides prerequisites, supported types, and delivery options. It is a single block of text but every clause adds useful information. While it could be bulleted for readability, it remains efficiently compact.

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

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

Given the tool's complexity (multiple types, nested params, multiple delivery channels) and no output schema, the description covers prerequisites, return value, supported types, and delivery details, including optional email/sms. It omits webhook delivery in the main description, but the schema covers it. Overall, it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by providing concrete examples for each subscription type (e.g., items:['5.02'] = officer change, topic:'fed') and after the 10/day SMS cap which is not in the schema. This pushes 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 begins with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this tool from siblings like unsubscribe, list_subscriptions, and recent_alerts by focusing on creation and mentions it returns the new subscription id.

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 context on when to use the tool, stating it requires a Pipeworx OAuth account and explaining the feed channel can be pulled via recent_alerts or a GET endpoint. It gives supported types and delivery options, but does not explicitly mention alternatives like list_subscriptions or when not to use, though these are 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds value by explaining the response structure (category-bucketed examples with tool+argument shapes) and the optional topic focus 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 front-loaded with example queries and packed with valuable details. Every sentence earns its place—categories, return payload, parameter behavior, and usage timing—though it could be slightly tightened.

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 clearly communicates what the user will get (categorized example questions with tool+argument shapes), how to vary the output, and when to use it. It fully serves its onboarding purpose.

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

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

Schema coverage is 100% and already describes topic, but the description adds semantic meaning: calling with no arguments gives the full spread, while passing topic focuses the results. It also gives concrete examples like 'finance', 'pharma', 'betting'.

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 exactly what the tool does: it returns category-bucketed example questions for onboarding, each with the exact tool and argument shape needed. This clearly distinguishes it from siblings like discover_tools and ask_pipeworx by positioning it as the meta-level entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. It also explains the no-argument vs topic-filtered modes, providing concrete 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?

Beyond annotations, the description discloses that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. It also notes ownership enforcement, adding permission 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?

Two concise sentences, front-loaded with the primary action and immediately followed by key behavioral details. 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?

For a simple one-parameter mutation tool with good annotations, the description covers purpose, ownership, and post-effect. No output schema is needed for this simple operation.

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

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

Schema coverage is 100% with a clear description of the id parameter. The tool description adds no additional param info beyond 'by id', so the baseline 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by ID, using the verb 'Cancel' and resource 'subscription'. It distinguishes from siblings like subscribe and list_subscriptions by specifying ownership enforcement and the deactivation behavior.

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

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

Provides clear context that only your own subscriptions can be cancelled and that deactivation preserves historical events via recent_alerts. It doesn't explicitly name alternatives, but the context implies it's the cancellation counterpart to subscribe.

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; the description adds critical behavioral nuance by explaining that could_not_verify is a system failure (not evidence) and unsupported means no source coverage. This prevents misuse of verdict values, which is valuable beyond what annotations provide.

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

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

The description is longer than average but front-loaded with trigger phrases and a clear purpose. Each section (examples, routing, verdict semantics, efficiency) earns its place, though the 'Replaces 4–6 sequential calls' benefit could be considered redundant.

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 thoroughly explains the return values (verdicts), the distinction between could_not_verify and unsupported, and the two processing paths. It also provides usage guidance and tolerance configuration, making it self-contained for an agent.

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

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

Schema covers 100% of parameters with clear descriptions, so baseline is 3. The description adds practical semantics for tolerance_pct, explaining it overrides the wording-implied tolerance and recommending 1-2% for hallucination detection, which goes beyond the schema's generic 'max percent deviation.'

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

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

States a clear verb+resource: natural-language claim verification against authoritative sources. Distinguishes from siblings by explaining the SEC EDGAR/XBRL fast path for company-financial claims and automatic fallback for any other claim. Examples of user phrasings 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It also notes the tool replaces multiple sequential calls, implying it is the canonical verification entry point. However, it does not name specific sibling tools to avoid.

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