Regulatory Catalysts

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description complements this by explaining the probing behavior, scoring range, and return structure. It also discloses that Anthropic calls require a BYO key and incur direct costs, which is important transparency 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?

The description is three sentences with no wasted words. Each sentence adds critical information: purpose and scoring, model options with cost implication, and output structure. Front-loaded with the main action.

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

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

Given no output schema, the description adequately explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers required vs optional parameters and their behavioral implications. Slightly more detail on what 'signals' includes would push this to 5.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining defaults (Workers AI Llama-3.3-70b), the role of `_apiKey` (only needed for 'anthropic' models), and the effect of `context` (disambiguation). It also summarizes the return format, which is not in the schema.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs for what they know about a business / brand / product / topic'), and clarifies the output (score 0-100 per model). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on AI knowledge visibility rather than just competitor 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 description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also clarifies when to use the optional models and API key. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, which would improve it further.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds context about routing to 5,114 tools, returning citations with stable URIs, and being a fast single call. No contradictions.

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

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

Description is long but well-structured: front-loads purpose, then guidelines and examples. Every sentence adds value, though could be slightly more concise.

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

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

Given the tool's complexity (5,114 tools, many sources), the description covers purpose, usage examples, alternatives, and output format (citations). No output schema, but description suffices.

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

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

Schema coverage is 100% with all aliases documented. Description mentions 'Routes the question' but doesn't add significant new meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions about current/historical data from many authoritative sources. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and gives specific examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides when to use this tool vs. alternatives (grounded for hallucination-resistant, deep_research for broad questions). Also gives many examples of suitable queries.

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 valuable behavioral context beyond annotations: source-preference ranking when a source is named, and that it falls back to nothing as a full working router. Annotations already indicate readOnly, idempotent, and non-destructive traits, and the description aligns 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 a single front-loaded paragraph that efficiently communicates identity, uniqueness, and usage. It is slightly wordy but each sentence contributes value.

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

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

Given the tool's complexity (router over 5k tools) and the lack of an output schema, the description covers purpose, behavior, and usage context adequately. No gaps are critical.

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

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

Schema coverage is 100%, with all six parameters (question and aliases) documented in the schema. The description does not add further semantic detail beyond noting it accepts the same arguments as ask_pipeworx, which is adequate given schema completeness.

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

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

The description clearly defines the tool as a beta version of ask_pipeworx, an identical universal router with the same scope and arguments, but with experimental routing improvements. It distinguishes from the stable ask_pipeworx sibling by specifying the 'source-preference ranking' 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?

The description advises using it exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router. It does not explicitly state when not to use it, but positions it as an experimental alternative, providing clear context for evaluation.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context: for companies it pulls specific financial data from SEC EDGAR/XBRL with proper handling of off-calendar fiscal years, and for drugs it pulls FAERS and FDA data. It also notes sorted results and citation URIs.

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 paragraph but is dense with useful information. It could be more structured with bullet points, but it remains concise without unnecessary words. Every sentence adds value.

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

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

Given the lack of an output schema, the description explains the return data: paired metrics and citation URIs. It covers both entity types thoroughly. The max items constraint is already in the schema, so no need to repeat. It provides sufficient context for an agent to determine suitability.

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 described. The description adds meaning beyond the schema: it explains the behavior for each type ('company' pulls financials, 'drug' pulls regulatory data) and provides examples of valid values (tickers/CIKs for company, drug names).

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

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

The description explicitly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides example queries and clearly distinguishes it from sibling tools like entity_profile, which handles single entities.

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

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

The description gives direct guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also quantifies the benefit by stating it replaces 8–15 sequential lookups, helping the agent decide when to use this tool.

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

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

Disclosures go well beyond annotations: account requirement, depth level behavior (parallel facets, gap recovery, contradictions scans), return format (findings packet with evidence, confidence, source, citation, gaps[]), time estimates (15-90s), and handling of large records (semantic excerpting). 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 comprehensive but verbose. Key info is front-loaded (account requirement, alternative tool). However, sentences are long and packed with details, which could be more concise. Still well-structured with logical flow.

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 (2 params, no output schema), the description covers all necessary context: prerequisites, usage boundaries, return format, timing, edge cases (gap recovery, contradictions, large records). It is complete enough for an agent to correctly 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 provides 100% coverage with descriptions for both parameters. Description adds context: explains what each depth level does in terms of facet count, hops, and features (gap recovery, contradictions). Also clarifies that question can be broad/multi-part and will be decomposed.

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 'Grounded multi-source research across Pipeworx's 1345 STRUCTURED data sources' in one call, decomposing questions into facets and routing to parallel tools. It distinguishes from sibling ask_pipeworx by noting this is not open-web search and is for broad/multi-part questions.

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 ('Best for broad/multi-part questions over structured data') and when not to use ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also mentions account requirements and provides alternative for unsigned users (ask_pipeworx).

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

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

Annotations already declare readOnly and idempotent hints. The description adds that results include names, descriptions, full input schemas with curated examples, and are ready to call without a second lookup. No contradictions.

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

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

Front-loaded with 'Find tools by describing the data or task.' Each sentence adds value: lists domains, describes return format, and gives usage advice. Slightly lengthy but well organized.

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 100% schema coverage and no output schema, the description explains the return format and that results are self-contained. It covers when to use and what to expect, but minor details like relevance ranking are 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 covers all 6 parameters with descriptions. The description adds context about aliases for query (task, q, description, search) and clarifies that limit controls top-N results. Baseline 3, extra info elevates 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 clearly states the tool finds tools based on data or task descriptions, listing example domains and emphasizing it returns ready-to-call results. This distinguishes it from sibling tools that are specific task tools.

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

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

Explicitly tells when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists scenarios like browsing, searching, discovering tools for various data types.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds valuable behavioral context: parallel fan-out, patent sunset soft-fail, and return field details.

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?

Well-structured with example queries first, then purpose, then output details. Slightly verbose but every sentence adds value; no fluff.

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

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

Despite lacking an output schema, the description thoroughly lists all return fields (CIK, filings, fundamentals, patents, news, LEI) and integration details, making it self-sufficient for an agent.

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

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

Schema coverage is 100%; description enriches each parameter with examples ('AAPL', '0000320193'), explains enum restriction ('company' only), and adds constraint on name vs ticker/CIK.

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

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

Clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific outputs, distinguishing it from sibling tools like resolve_entity.

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 advises to 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view' and provides a when-not-to-use condition (names not supported, use resolve_entity).

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds behavioral context: data is sourced from the Federal Register (keyless), meetings are sorted soonest-first, and filter options are explained (e.g., upcoming_only keeps today or later, with a note if none found). 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?

Description is a single paragraph but front-loaded with the main purpose. Each sentence adds useful information, though it is somewhat long. Could be broken into shorter sentences for clarity, but no wasted words.

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

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

Despite no output schema, the description fully documents the return structure: committee, meeting date (ISO when parseable) plus raw date text, topic, publication date, Federal Register URL, and document number, sorted soonest-first. Also mentions coverage of all FDA advisory committees and keyless access. Complete for a list tool.

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

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

Schema description coverage is 100% for all three parameters. The description adds significant meaning beyond the schema: limit range (1–20, default 10), committee as case-insensitive substring, upcoming_only default true, and behavior when no upcoming meetings (returns found rows with a note). Enriches understanding of defaults and edge cases.

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

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

Description clearly states it lists upcoming FDA advisory committee meetings from the Federal Register, covering oncology, gene therapy, and all committees. It uses specific verbs (lists, extracts, returns) and distinguishes from sibling tools like pdufa_catalysts by focusing on AdCom meetings rather than PDUFA dates.

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 use cases: 'Use for AdCom, advisory committee, panel vote, drug approval catalyst, FDA meeting calendar, upcoming biotech panels.' It does not explicitly mention when not to use or provide alternatives, but the context is clear and the purpose is well-defined.

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

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

Discloses destructive nature ('Delete') and adds context about clearing sensitive data. Annotations already indicate destructiveHint=true, and description reinforces and specifies what gets destroyed, adding value 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?

Concise: three sentences with no wasted words. First sentence states action, second gives usage context, third suggests related tools. Well-structured and front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, usage, related tools, and no additional information is necessary.

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 for the single parameter 'key'. Description does not add additional semantics beyond what is in the schema, meeting the baseline expectation.

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 states the action (delete) and resource (memory by key). Distinguishes itself from sibling tools 'remember' and 'recall' by specifying it is for deletion.

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

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

Explicitly describes when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall, implying 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?

Description explains the fetch-extract-emit process and output location. Annotations already declare readOnly=true and not destructive, and the description adds no contradiction. It transparently discloses the tool's idempotent, read-only nature.

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: purpose, process, use cases. Every sentence adds value with no padding. Front-loaded with the core action and standardized output.

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

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

Given the tool has 2 params, no output schema, and rich annotations, the description fully covers what the tool does, how it works, what the output looks like, and ideal use cases. 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% (both url and max_links described). The description adds context: for max_links, it mentions default (25) and max (50). This adds clarity beyond the schema's minimum-description attribute.

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

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

The description clearly identifies the tool's action: generate a production-ready llms.txt file for any URL. It specifies the target users (AI crawlers) and the output format, distinguishing it from siblings like scan_competitor_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 description lists explicit use cases (client indexing, own project, competitor audit) but does not contrast with nearby siblings or state when not to use the tool. The use cases are clear, but exclusion 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?

The description reveals that the tool searches SEC EDGAR 8-K filings 'keyless', which adds behavioral context beyond the annotations (readOnlyHint, openWorldHint, etc.). It explains the extraction method and output fields. No contradictions with annotations; the description complements them well.

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 informative paragraph, front-loaded with the core functionality. It lists many synonym phrases, which is helpful but slightly verbose. Overall, it is well-structured, though a tighter focus on the primary use case could improve conciseness.

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

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

Given no output schema, the description thoroughly explains the return fields (company, ticker, CIK, filing date, PDUFA date, snippet, URL, accession number). It also explains the data source, the binary event significance, and the 'keyless' access. This provides a complete picture for an agent to understand and use the tool effectively.

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

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

The schema already covers 100% of parameters with descriptions, but the tool description adds default values for 'limit' (8) and date windows ('since' 120 days ago, 'until' today). This extra context aids an agent in using defaults correctly. The description also reiterates the 'query' usage with examples, reinforcing 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 searches SEC EDGAR 8-K filings for PDUFA dates, a specific binary biotech catalyst. It lists the output fields and provides many alternative search phrasings, making the purpose unmistakable. While it doesn't explicitly differentiate from siblings, the specificity and detail earn a top score.

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 a clear list of use cases (e.g., 'PDUFA date', 'FDA decision date') and implies the domain of biotech binary events. It does not explicitly state when not to use or contrast with alternatives like 'fda_adcom_calendar', but the context is sufficiently defined for an agent to decide.

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

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

Discloses key behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, team reads digests daily, and signal affects roadmap. No contradiction with annotations.

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

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

The description is concise and well-structured: first sentence states purpose, then usage guidelines, then behavioral notes. No fluff. Every sentence adds value.

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

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

Given the tool's simplicity and the richness of annotations and schema coverage, the description is complete. No output schema is needed; the tool sends feedback and the description adequately covers what the agent needs to know.

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

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

Schema description coverage is 100%. The description adds meaning for each parameter: explains the 'type' enum values in detail, suggests format for 'message' (1-2 sentences, 2000 chars max), and clarifies optional 'context' fields.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and resources (feedback categories) and distinguishes itself from siblings which are mostly query/analysis tools.

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

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

Explicitly provides when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also includes a clear exclusion: 'don't paste the end-user's prompt.'

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, destructiveHint=false. The description adds valuable context beyond annotations: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). 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 concise (4 sentences) and well-structured: it first states the main output, then lists use cases, and finally provides source and caching details. Every sentence adds value, and the key information is front-loaded.

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

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

Despite no output schema, the description adequately explains the return shape (top tools, top packs, total call volume) and includes caching details. With only one parameter and no required fields, the description covers all necessary context for an agent to use the tool correctly.

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

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

The input schema is fully covered (100%) with an enum for 'window' and a basic description. The description supplements this by explaining that shorter windows surface hot current data and longer windows show steady-state demand, which aids parameter selection.

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

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

The description specifically states it returns 'top tools, top packs, and total call volume' over a selectable window (24h, 7d, 30d). It clearly differentiates from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on trending usage 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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. While it doesn't explicitly state when not to use it, the use cases are clear and the context signals list siblings, helping an agent decide when to call this tool versus others like 'ask_pipeworx' or 'discover_tools'.

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

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

The description goes well beyond the existing annotations (readOnly, idempotent, not destructive) by detailing the 60-day snapshot TTL, dependence on snapshotting enablement, daily close data vs. intraday, and the specific response structure. This provides rich behavioral context 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 well-structured with clear sections (purpose, response format, limits). It is front-loaded with the core purpose. While every sentence adds value, the description is somewhat verbose (e.g., including default values already in schema). Overall efficient and organized.

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 comprehensively explains the response format (tracked, expired, snapshot_dates) and their fields. It also covers limitations and default behavior for both parameters. This provides sufficient context for an agent to use the tool correctly without ambiguity.

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 clearly defines both parameters (days, window) with defaults and ranges. The description repeats this information with minor clarification (e.g., 'lookback', 'snapshot family'), but adds little new semantic meaning beyond what the schema already provides. Thus a baseline score of 3 is appropriate.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and trend. It distinguishes itself from the sibling 'polymarket_edges' tool by focusing on time-series analysis rather than current snapshots, and mentions expired opportunities which are not present in the raw snapshots.

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

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

The description explains when to use the tool: to answer 'how long has this edge existed and is it shrinking?' It provides context on the significance of fresh vs. old edges. However, it does not explicitly contrast with the sibling 'polymarket_edges' or other tools, though the context is clear enough for an agent to infer appropriate usage.

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

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

The description adds significant behavioral context beyond annotations: walks the ladder, returns verdict (clean/degraded/cannot_fill), warns about thin books and directional risk. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; the description enriches this with operational details. 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 well-structured with uppercase mode headers (SINGLE-MARKET, BASKET) and clear sections. While somewhat lengthy, every sentence adds value. It front-loads the core purpose and requirements. Minor deduction for slight verbosity, but overall effective.

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 lack of an output schema, the description comprehensively lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single; theoretical_sum, capture_ratio, profit_usd, thin_legs, etc. for basket). It also explains the risk of partial fills and directional exposure, making the tool self-contained for an AI 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?

Adds meaning beyond the input schema: explains that 'market' and 'event' are mutually required, clarifies size_usd interpretation for buys vs sells and basket notionals, details side defaults and behavior. Schema coverage is 100%, and the description enhances understanding by providing context and constraints.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and provides specific verbs like 'check' and 'returns'. The purpose is well-differentiated from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills create directional risk) and provides context for both modes, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) and explaining edge cases where the tool returns non-standard outputs. 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 lengthy but well-structured with clear section breaks (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. A slight reduction in redundancy (e.g., repeating 'pre-mapped') could improve conciseness without losing clarity.

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 comprehensively explains the response structure: leg-by-leg prices, spread calculations, and all safety fields. It covers input modes, edge cases, and caveats. For a complex tool with 0 required parameters, this provides sufficient context for an AI agent to understand 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 provides 100% coverage with descriptions for all three parameters, including examples. The description adds value by explaining the interaction between topic and explicit parameters (overrides), and the behavior when both are provided. However, the schema already does a good job, so the description's incremental value is moderate.

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's a cross-venue spread tool comparing Kalshi and Polymarket, with specific verb 'spread' and resource 'cross-venue'. It distinguishes itself from siblings by being the only tool focused on this specific pairwise comparison.

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

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

The description explicitly explains when to use each mode (topic vs explicit parameters) and provides detailed warnings about when spreads are not meaningful (compatibility_warning, temporal alignment, skipped counts). However, it doesn't explicitly contrast with sibling tools like 'polymarket_arbitrage' or 'polymarket_edges', leaving some ambiguity about when to choose this over them.

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

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

Annotations already indicate read-only, idempotent, non-destructive; description adds scoping (anonymous IP, BYO key hash, account ID) and pairing 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 sentences, front-loaded with main action, no extraneous information.

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

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

For a tool with one optional parameter and no output schema, the description covers usage, scoping, and tool pairing adequately.

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

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

Schema has 100% coverage (key property described); description adds that omitting key lists all keys, which is not in schema but complements it.

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 retrieves a value saved via 'remember' or lists all keys if omitted, distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

Explicitly states when to use (look up stored context) and pairs with 'remember' and 'forget', but lacks explicit when-not-to-use guidance.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds key behavior: mark_read flags events as read to affect subsequent calls. No contradictions.

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

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

Description is a single paragraph with good flow but includes some redundancy (e.g., 'Flag the returned events read' is explained inline). Could be more concise.

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

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

Without output schema, description explains return fields (source, citation_uri, payload). Also mentions alternative URL, making it fairly complete for a read-only polling tool.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). Description adds examples (e.g., 'sec_8k' for type) and explains mark_read effect, but adds limited new meaning beyond 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?

Description clearly states the tool pulls fired events from subscription feed and specifies returned fields (source, citation_uri, payload). Distinguishes from sibling tools like list_subscriptions by focusing on recent alerts.

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

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

Provides context for usage: polling is fine and notes an alternative URL for scripts/dashboards. Could be more explicit about when not to use, but overall gives useful guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial context: fans out to multiple sources, fallback behavior, soft-fail for USPTO, and return format (structured changes grouped by source with total_changes and citation URIs). 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 a single dense paragraph containing all necessary information. It could be more structured (e.g., bullet points) but every sentence is valuable and front-loaded with examples. Slightly long but justified.

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

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

Despite no output schema, the description explains the return format (changes grouped by source, total_changes, citation URIs). It addresses edge cases (GDELT rate-limited fallback, USPTO sunset) and provides usage context. Complete given the tool complexity and good 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% for 3 parameters. The description adds examples for `since` (relative shorthands, typical monitoring value), clarifies `type` is limited to 'company', and gives examples for `value`. 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 begins with multiple usage examples ("What's new with X", "latest on Y", etc.) and clearly states it is a change feed for a company in the last N days. It explicitly distinguishes from the sibling tool entity_profile, which is for static profiles.

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

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

Explicitly states when to use this tool (for change feed) and when not (use entity_profile instead). Also provides context on fallback behavior (GDELT→GNews, USPTO soft-fail) and typical monitoring value for `since`.

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

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

Annotations already indicate idempotence and non-destructiveness; the description adds context on scoping by identifier and persistence duration 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?

Well-structured with front-loaded purpose. Each sentence adds value, though slightly verbose but justified.

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

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

For a simple key-value store, the description covers purpose, usage, scope, persistence, and pairing with siblings. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds usage examples for key and value, enhancing clarity 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 clearly states the tool's purpose ('Save data the agent will need to reuse later') and distinguishes it from siblings like recall and forget by specifying the action and scope.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and pairs with recall and forget. Also clarifies behavior for authenticated vs anonymous sessions.

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

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

Discloses that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups. Also details output per type including citation URIs. Consistent with annotations (readOnly, idempotent, non-destructive).

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?

Starts with example queries, then states purpose, usage guideline, and details per type. All sentences are informative, though slightly verbose. No waste.

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?

Fully explains inputs and outputs for both entity types, including return fields and citation URIs. Since there is no output schema, the description carries the full burden and does so completely.

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

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

Adds significant meaning beyond the input schema: explains that 'value' accepts ticker, CIK, or name for company and brand/generic name for drug, includes examples, and mentions auto-disambiguation. Schema coverage is 100% but description enriches it.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with example queries. It distinguishes itself from siblings by emphasizing it should be used first when needing an 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Lists supported types and their output. Lacks explicit when-not-to-use or alternatives, but the context of sibling tools and the clear use case compensate.

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 clearly indicate readOnlyHint, idempotentHint, safe. Description adds that it calls ai_visibility_check multiple times, ranks results, and returns structured output. No contradictions; adds context 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 with clear front-loading of purpose. No wasted words: describes action, inputs, output, and example usage efficiently.

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

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

Despite no output schema, description specifies return format (ranked list with score, confidence, signal density). Input parameters fully covered in schema; description adds behavioral details. Complete for a tool of this complexity.

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

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

Schema covers all parameters (100% coverage). Description adds usage context: first entity treated as subject, models list alternatives, context for disambiguation. Provides value beyond 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?

Description clearly states it compares AI visibility across multiple entities, probing with ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (general comparison).

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

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

Description explicitly states usefulness for competitive AI-marketing audits with an example question. It implies when to use but does not explicitly mention when not to use or alternative tools.

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

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

Annotations already indicate idempotent, read-only behavior. The description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the 'sources_failed' field will list timeouts. This goes beyond annotations to warn about potential delays and error handling.

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 usage, but it is a single dense paragraph. It covers all necessary information without being overly verbose, though breaking into short sentences could improve readability. It earns its length by providing critical timing and ecosystem details.

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

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

Given the tool's complexity (composite of two external sources, multiple return fields), the description adequately covers inputs, outputs (summary block fields, per-advisory details, links, alternative versions), limitations (npm only), and edge cases (partial failures, timing). No output schema exists, so the description fills that gap effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions scoped packages are accepted (already in schema) and version defaults to latest (already implied by optional parameter). No additional parameter constraints or format details are provided.

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

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

The description clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the verb 'scan' and resource 'dependency' with detailed context, effectively distinguishing it from sibling tools that focus on other ecosystems or entities.

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

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

The description explicitly tells when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies ecosystem limitations ('NPM ecosystem only in v1') and directs users to other tools for other ecosystems, providing clear 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?

Rich disclosure beyond annotations: OAuth requirement, persistence constraints, type-specific details, delivery options, rate limit (10/day for SMS), webhook secret one-time return, auto-disable after 10 failures. 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?

Description is comprehensive but well-structured. Front-loaded with purpose and return value, then requirements, types, delivery channels. Every sentence adds value without redundancy.

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

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

Given complexity (3 params, nested objects, no output schema), description covers all aspects: types, params, delivery, OAuth, rate limits, failure handling, return value. Completely adequate for effective tool use.

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

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

Schema coverage 100%, description adds examples and constraints for each type-specific param. Explains delivery object with format, verification, and limits. Adds meaning beyond schema (e.g., webhook secret, auto-disable).

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 uses specific verb 'Create' and resource 'proactive monitoring subscription', clearly states return value. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

States prerequisite (OAuth account) and lists supported types with examples. Explicitly excludes anonymous/BYO users. Delivery channel guidance provided. Could be more explicit about when to use vs. other monitoring tools, but adequate.

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

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

Annotations already indicate read-only, idempotent, non-destructive, open-world. Description adds that it returns live categorized examples, can be called with no arguments for full spread, and provides tool shapes. No contradictions.

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

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

Description is slightly long but well-structured: starts with common user queries, then explains output, calling conventions, and usage guidance. Information is front-loaded and earned.

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?

Fully explains what the tool does, what it returns (categorized examples with tool shapes), how and when to use it. No output schema, but description covers return values adequately.

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, so baseline is 3. Description adds value by explaining the effect of omitting topic ('for cross-category spread') and providing example focus areas beyond the schema's list.

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 states it is an onboarding entry point that returns categorized example questions with tool and argument shapes. Distinguishes from siblings by instructing to use this first when uncertain about Pipeworx's capabilities.

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, or to learn how to call the meta-tools.' Also mentions optional topic parameter to focus on a specific area.

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

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

Adds valuable context beyond annotations: explains deactivation instead of deletion, ownership enforcement, and historical event preservation via 'recent_alerts'.

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 focused sentences with no wasted words; front-loaded with core action and critical constraints.

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?

Fully explains the tool's behavior for a single-parameter, no-output-schema tool, including side effects and linkages to historical data.

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

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

Schema covers 100% of the parameter with a clear description; the tool description does not provide additional details about the 'id' parameter 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?

Clearly states the action (Cancel) and resource (subscription by id). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying cancellation of own 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?

Provides clear context for usage (own subscriptions only) but does not explicitly state when not to use it or compare to alternatives.

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