Nih Reporter

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that Anthropic calls require a BYO key and direct payment, and details the return structure (per-model score, confidence, signals, raw_response + combined view). This enriches 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?

Two well-structured sentences convey all essential information. No redundancy; each clause earns its place by specifying purpose, default behavior, optional features, return type, and use cases.

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

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

Given the comprehensive annotations and schema, the description covers core aspects: default model, optional Anthropic, return format, and use cases. Minor omissions (e.g., error handling, rate limits) do not detract from overall completeness for a read-only probe 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 parameter descriptions. The description adds value by explaining entity scope, the meaning of models (omit for workers-ai), the _apiKey requirement, and the disambiguation role of context, going 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model and optional Anthropic probe, making the purpose distinct 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?

The description provides use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use each model (default vs. BYO key). No explicit exclusions or alternatives to sibling tools are given, but 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses routing behavior ('routes the question to the right one of 5,462 tools'), argument filling, and the output format ('structured answer with stable pipeworx:// citation URIs'). It also mentions 'one fast call' and tier availability. This adds useful context 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 long but well-structured, with clear segments: preference over web search, supported domains, trigger phrases, examples, default entry point note, escalation paths, and a note on breaking news. It is slightly repetitive ('PREFER OVER WEB SEARCH' and 'START HERE') but every section serves a distinct 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 general-purpose routing tool with no output schema, the description thoroughly covers what the tool does, when to use it, what output to expect (structured answer with citation URIs), and how it relates to sibling tools. The agent has enough context 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?

The input schema fully describes the 'question' parameter with aliases (100% coverage), so the description's job is limited. It provides example queries and mentions 'fills arguments' but does not add specific parameter-level semantics beyond what the schema already has. 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 states a clear, specific purpose: it routes factual questions to the right tool/source and returns structured answers with citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default 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?

Explicit guidance is given: prefer over web search, use for specific question types (what is, look up, find, get the latest, how much, current). It also specifies when to escalate to ask_pipeworx_grounded or deep_research, providing clear when-to-use vs. when-not-to-use alternatives.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses its beta status, that no candidate is currently active, that it currently matches ask_pipeworx exactly, and that it is a full working router, not a fallback. This added context is highly valuable.

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?

Four front-loaded sentences, each carrying distinct information: beta identity, current state, usage instruction, and fallback clarification. No wasted words; 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?

The description fully covers what the tool is, its current behavior, and how to use it. Given the sibling context, the response shape reference to ask_pipeworx is sufficient, and there is no output schema to explain.

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

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

Schema description coverage is 100% with all aliases fully documented. The description mentions 'same arguments' as ask_pipeworx but adds no parameter-specific semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly defines this as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by its experimental routing improvements.

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 instructs to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router to decide merges. This provides a clear when-to-use criterion and implies the alternative for stability.

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 key behavioral traits beyond the annotations: it 'EXTRACTS the answer using ONLY what the tool result contains,' returns a specific structure with verbatim evidence, and lists four explicit refusal_reason values. It also discloses the extra LLM call cost. This goes well beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is dense but every sentence earns its place: mode definition, routing/extraction explanation, return format with refusal reasons, usage guidance, and cost trade-off. It's well-structured and front-loaded with the core purpose, and no content is superfluous.

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 provides a full specification of the return object on success and refusal, including all refusal_reason values. It also explains the routing breadth, usage context, and cost, making it complete for both selection and invocation. This is a complex tool, and the description covers all necessary context.

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

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

The input schema already documents all six parameters (question plus five aliases) with 100% coverage, so the description doesn't need to explain them. The description only generically mentions that the tool 'fills arguments,' and does not add specific value about parameter syntax or semantics beyond what the schema already provides. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from sibling ask_pipeworx by the 'grounded' behavior. It explicitly states what the tool does: routes to appropriate tools, fetches data, and extracts answers only from the tool result, returning evidence and refusal reasons.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an explicit alternative ('prefer ask_pipeworx for casual lookups') and mentions the cost trade-off, making it clear when to choose this tool vs. its sibling.

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 extensive behavioral context beyond annotations, covering market resolution, classification, fan-out, response shapes, resolver contract, parent event extraction, news fields, safety short-circuits, and resolution-rule risk. It details blocking conditions like low-confidence matches and closed markets. No contradiction with annotations.

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

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

The description is long but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and examples. Information is front-loaded with the main purpose. While some sentences are dense, every part adds value given the tool's complexity. Could be slightly more concise but still 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?

Despite lacking an output schema, the description thoroughly explains return values, edge cases, and blocking conditions. It covers resolver confidence, parent events, news fallbacks, and resolution rules. For a tool with 3 parameters, this provides complete contextual guidance 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 description coverage is 100%, so baseline is 3. The description adds context for the 'market' parameter (slug, URL, question text) and explains the 'depth' and 'include_raw' parameters with behavior details (quick vs thorough, raw vs summarized). These additions provide meaningful guidance 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 clear action ('Research a Polymarket bet') and specifies the resource ('Pipeworx data'). It provides concrete examples of use cases and distinguishes itself from sibling tools by its comprehensive research scope. The verb 'research' and resource 'bet' are 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 the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classification examples and fan-out examples that guide the agent on expected behavior. Safety checks and resolution-rule risk warnings serve as implicit guidance on when results may be unreliable.

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 specific behavioral traits: for 'company' type pulls 10-K financials from SEC EDGAR/XBRL with off-calendar handling, for 'drug' pulls FAERS and FDA counts. Describes sorting by primary metric and output format with citation URIs. Annotations already provide read-only/open-world hints, and description enriches 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?

Dense single paragraph front-loaded with trigger phrases and key usage guidance. Every sentence adds 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?

Covers entity types, data sources, sorting, output format (paired data + URIs). Lack of output schema means description must convey return structure; it does so adequately but could be more explicit about the structured nature of the response.

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

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

Schema covers both parameters fully. Description adds concrete examples (tickers, drug names) and clarifies data sources for each type enum value, enhancing understanding beyond schema 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 lists multiple trigger phrases ('Compare X and Y', 'head to head') and explicitly states it compares 2–5 companies or drugs in one call. It distinguishes from siblings like entity_profile by emphasizing parallel comparison over sequential 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and notes it 'replaces 8–15 sequential lookups'. No exclusion cases or when-not-to-use, but the guidance is strong and contextually 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 signal readOnly, openWorld, and idempotent. The description adds substantial context: account/paid-plan requirements, latency bounds (15-60s, up to ~90s for thorough), gap/contradiction behavior, citation resolvability, semantic excerpting, and the caveat that non-catalog topics return mostly empty gaps[]. 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 dense, and every sentence contributes distinct information: auth, core function, use cases, output structure, latency, and failure modes. It front-loads the account requirement and core identity before diving into details. Slightly verbose but justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining the return value. It thoroughly covers the findings packet (verbatim evidence + confidence + source + fetched_at + citation), gaps[], contradictions[], hop field, and citation resolvability. It also explains the parallel tool-routing mechanism and account gating. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the paid-plan implication of depth:"thorough" ("depth:"thorough" needs a paid plan") and by giving natural-language examples of the question type. It also explains depth's behavioral impact (facet count, gap recovery hops) beyond the schema's enum descriptions.

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

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

The description opens with a specific verb+resource: "Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call." It explicitly distinguishes from ask_pipeworx by stating "For a single lookup use ask_pipeworx (one LLM call, not many)" and highlights that this is "NOT open-web search." The purpose is unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance: "Best for broad/multi-part questions over structured data," "For a single lookup use ask_pipeworx," "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx," and "If you are not signed in, use ask_pipeworx instead." It even covers the fallback path for not-signed-in users.

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 adds value beyond annotations by stating the tool returns top-N most relevant tools with full schemas and curated examples, ready to call directly. Annotations already indicate read-only and idempotent, but the description enriches with behavioral 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?

Single, well-structured paragraph. Every sentence adds value: first defines purpose, then lists domains, then explains output format, then usage advice. 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 discovery tool without output schema, the description sufficiently explains what is returned (names, descriptions, full schemas with examples). Covers the essential context for an agent to use it 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% with each parameter described. Description adds meaning by listing aliases and providing concrete examples (e.g., 'look up FDA drug approvals'), which enhances clarity beyond the schema alone.

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

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

The description clearly states the tool discovers tools based on a task description, listing many domains (SEC filings, FDA drugs, etc.). It distinguishes itself from siblings by being a meta-tool for browsing the tool set, which is unique among the listed siblings.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set'. Also lists use cases like 'browse, search, look up, discover'. Provides clear context for when to use, though no explicit when-not, it's well understood.

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

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

Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: returned fields (CIK, filings with URIs, fundamentals, patents, news, LEI), sorting of fundamentals, and the patents API sunset soft-fail. No contradictions.

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

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

The description is dense but front-loaded with example queries. Every sentence adds value, though some details (like the patents sunset note) could be slightly more concise. Overall well-structured and informative.

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 absence of an output schema, the description thoroughly explains the return structure (filings, fundamentals, patents, news, LEI) and handling of the patents soft-fail. It covers nearly all aspects, though it omits potential error conditions or rate limits.

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 valuable context: the 'type' parameter is limited to 'company' with future plans, and 'value' specifies allowed formats (ticker or CIK) and explicitly excludes names. This goes beyond the schema definitions.

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

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

The description clearly identifies the tool's purpose: generating a holistic profile of a US public company from multiple sources in a single parallel call. It provides specific example queries and explicitly states that it should replace chaining multiple single-purpose 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 states when to use the tool ('when the user asks for a holistic view') and when not to (for name inputs, directing to resolve_entity). It also outlines the data sources and mentions a soft-fail for patents, providing clear 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 destructive nature (destructiveHint=true). Description adds context about clearing sensitive data and ensuring privacy, but doesn't contradict annotations.

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

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

Two concise sentences that directly convey purpose and usage without any unnecessary words 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?

Given the tool's simplicity (1 parameter, no output schema, no nested objects), the description fully covers purpose, usage guidelines, and behavioral context.

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

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

Schema coverage is 100% for the single 'key' parameter, which has a clear description. The tool description adds no extra meaning beyond 'by key', so 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?

Description clearly states the action (delete) and the resource (memory by key). It also distinguishes from siblings 'remember' and 'recall' by focusing on 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 lists when to use: context is stale, task is done, or clearing sensitive data. Also suggests pairing with siblings, providing clear 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 details the internal steps: fetching the page, extracting title/description/links, and emitting markdown. This adds significant context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). 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 two sentences long, front-loads the core purpose, then adds process and use cases. Every word serves a purpose; there is no repetition 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 tool has only two parameters, no output schema, and the description explains the output is a single text blob ready to drop, the description is fully complete. An agent can understand input, behavior, and output without any gaps.

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

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

The schema already describes both parameters (url, max_links) with 100% coverage. The description adds default and max values for max_links (default 25, max 50), which enhances the agent's understanding but is not critical since the schema provides basic meaning.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, which is a specific and distinct action among sibling tools. It uses a specific verb and resource, and the additional context about AI crawlers and format makes the purpose unmistakable.

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

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

The description lists concrete use cases (getting a client site indexed, drafting for own project, auditing competitor), which helps an agent decide when to use it. However, it does not explicitly state when not to use it or directly mention alternatives, though the sibling list provides context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by clarifying that the ID is numeric and distinct from project number, and enumerates the returned data fields (abstract, relevance, terms, PIs, organization, dates, award amount), which goes beyond minimal 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?

Two sentences, front-loaded with the key operation and identifier, followed by a useful pointer to an alternative. Every phrase earns its place; no fluff 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 single-record fetch with one parameter, an output schema present, and strong annotations, the description fully covers what the tool does, what it returns, and when to instead use a sibling. No critical gaps.

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

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

Schema covers appl_id with 'NIH application ID (integer)' at 100% coverage, so baseline is 3. The description adds extra meaning by noting it is numeric and 'distinct from project number,' which prevents a common confusion. This raises it above baseline.

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

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

The description uses a specific verb ('Fetch') and resource ('NIH project application record') with a precise identifier ('application ID'), and lists returned content. It also distinguishes itself from sibling nih_grant_award_history by directing users there for multi-year history.

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 an alternative: 'Use nih_grant_award_history for multi-year award history.' This clearly tells the agent when not to use this tool and which sibling to choose instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about returned fields and the include_inactive parameter, but doesn't reveal additional behavioral traits 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?

Two compact sentences with no fluff. Every sentence adds value: the first defines purpose and output, the second gives usage context. Ideal 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?

With one optional parameter, no output schema, and full annotation coverage, the description is complete. It covers what the tool does, what it returns, and when to use it.

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 the single parameter 'include_inactive', which already has a good description. The tool description adds no extra meaning to this parameter, 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 'List the caller's active subscriptions' and lists returned fields. It distinguishes from sibling tools like subscribe and unsubscribe implicitly through its read-only nature, but doesn't explicitly differentiate.

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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it doesn't mention alternatives or when not to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: results disclose truncation, and figures represent reported federal obligations—not valuation, revenue, or total research spending. This prevents misinterpretation of the data and adds context that annotations alone do not provide.

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

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

The description is two sentences, front-loaded with the main action and purpose. It avoids filler and every clause adds value (scope, output dimensions, truncation disclosure, data semantics).

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 optional parameters, no output schema), the description covers the search scope, output granularity, and data interpretation. It does not explain pagination, limit defaults, or how parameters combine (e.g., AND vs OR), but the examples in the schema partially fill this gap. The description is adequate for a read-only, bounded aggregation 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 description mentions 'topic, organization, or PI search' which maps to the query, organization, and pi_name parameters, adding some meaning beyond the bare schema. However, it does not explain the fiscal year parameters (to_fiscal_year, from_fiscal_year) or their expected format/behavior. Since schema coverage is 0%, the description only partially compensates for missing parameter documentation.

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

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

The description uses a specific verb ('Summarize') with a clear resource ('NIH award dollars and record counts') and defines the grouping dimensions (fiscal year, recipient organization, PI, activity code, funding mechanism). It distinguishes this tool from siblings like nih_funding_expirations or nih_grant_award_history by focusing on concentration/summary rather than individual awards or expirations.

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 'bounded topic, organization, or PI search' provides clear context on when to use the tool, implying the user should narrow their query to one of these scopes. However, it does not explicitly mention alternatives or when not to use it, so a small deduction from 5 is applied.

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, so the safety profile is covered. The description adds value beyond annotations by warning that end dates can be extended, renewed, supplemented, or updated, which is crucial behavioral context for interpreting results.

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 long, front-loaded with the primary purpose, and every clause adds meaning. The caveat about monitoring is concise and valuable.

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 relative simplicity of the parameters and the strong annotations, the description adequately covers what the tool does and the key caveat. The only gap is the incomplete parameter descriptions, but overall context is sufficient 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 50%: 'days' and 'limit' have descriptions, while 'query' and 'organization' do not. The description partially compensates by mapping 'matching a topic or organization' to those parameters, but it doesn't add detail about their expected formats or 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 function: finding active NIH projects matching a topic or organization whose project period is ending soon. This distinguishes it from sibling tools like nih_new_grant_awards or search_grants, which focus on other aspects.

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

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

The description provides clear context on how to interpret results ('monitoring cue only') and what the end date does not prove, which guides appropriate use. It does not explicitly name alternative tools or exclusion criteria, but the guidance is sufficient for most use cases.

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 readOnlyHint, the description adds critical data interpretation: annual award amounts are obligations per fiscal year, not revenue, cash received, or guaranteed future funding. This prevents misinterpretation of returned data and explains cumulative reported funding, which is valuable context not provided by annotations.

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

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

The description is two sentences, each earning its place: the first lists the tool's function and deliverables, the second clarifies a critical data nuance. Information is front-loaded with no redundancy, making it highly efficient.

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

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

With only one parameter, read-only annotations, and no output schema, the description sufficiently covers the tool's purpose, data elements, and interpretive caveat. It does not describe the exact return format, but for a simple historical look-up this is acceptable.

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

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

The schema already provides a clear description and examples for core_project_num (e.g., R43GM128494 or UG1HD078437), achieving 100% coverage. The tool description does not add further parameter-specific guidance, so the schema carries the burden and the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Build the annual NIH award history'), the scope ('for one core project number'), and the contents (award, direct/indirect cost, budget dates, application type, cumulative reported funding). This distinguishes it from broader sibling tools like nih_funding_concentration or search_grants.

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

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

The description implies usage for a single project's annual history and clarifies the meaning of award amounts, but it does not explicitly mention when to prefer this tool over alternatives or provide exclusions. A direct reference to sibling tools for multi-project or summary queries would strengthen this dimension.

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 valuable behavioral context beyond these: it clarifies that publication linkage reflects acknowledged grant support (not impact/causality) and that the sample is bounded. This helps prevent misinterpretation of results.

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

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

The description is two sentences: the first states the core action, the second adds a crucial caveat about what the linkage is not. No filler or redundant repetition; it is front-loaded and 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?

There is no output schema, so the description must clarify return values. It mentions 'return a bounded PMID sample' and implies a count, but does not specify the exact response structure, field names, or whether pagination exists. For a simple tool this is adequate but incomplete for a detailed invocation.

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

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

Schema description coverage is only 50%: 'limit' is well-described in the schema, but 'core_project_num' has no description. The tool description only repeats 'core project number' and 'bounded PMID sample', adding little meaning beyond parameter names. The schema example shows a format (UG1HD078437), but the description does not compensate for the undocumented required parameter.

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

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

The description uses a specific verb 'Count' with a clear resource ('publications linked by NIH RePORTER to a core project number') and specifies the output ('bounded PMID sample'). It also explicitly distinguishes itself from citation-impact measures, which differentiates it from sibling tools like search_publications or validate_claim.

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

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

The description provides an explicit when-not by stating it is 'not a citation-impact, product-readiness, or causal-attribution measure,' which tells the agent not to use this tool for those purposes. However, it does not name alternative tools or provide explicit 'use when' conditions, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context about optional restrictions and a caveat on interpretation, but does not disclose return format, pagination, or data update characteristics, leaving a moderate transparency gap.

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 main action and followed by use cases and a caveat. Every sentence earns its place with no redundant 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 list-style tool with no output schema, the description covers purpose, optional filters, use cases, and a caution. It does not describe output structure or data freshness, but the schema provides field-level details for most parameters, making it reasonably complete.

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

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

Schema coverage is 67%, and the description compensates by enumerating filter dimensions: topic, organization, state, institute, activity code, and SBIR/STTR. This gives meaning to parameters that lack schema descriptions (ic, state, organization) and reinforces the semantics of others.

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 'Find recently issued NIH awards' with a specific verb and resource, and lists distinct filters like new competing applications and SBIR/STTR. This differentiates it from sibling grant tools such as nih_funding_expirations or nih_grant_award_history.

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?

Second sentence provides clear use cases ('financing and emerging-program monitoring') and a caution about commercial validation. It lacks explicit naming of alternative tools, but the context is sufficiently clear for an agent to 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral context: wildcard matching behavior, the need to verify recipient identity, and the interpretation of award amounts as federal obligations. This enriches the agent's understanding of how the tool behaves and how to interpret results without contradicting the annotations.

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

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

The description is concise and well-structured: the first sentence clearly defines the tool's purpose, and the second provides critical cautions. No word is wasted, and all information is relevant 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?

The tool has 3 parameters, no output schema, and annotations that clarify safety. The description covers purpose, usage, and data interpretation, which is sufficient for most use cases. It could be more complete by describing the output format (e.g., rows vs. aggregated statistics) or whether it returns all years or only matching ones, but the given information is adequate given the 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 description coverage is low (33%), so the description must compensate. It adds wildcard matching semantics for the organization parameter and implies fiscal year parameters are used for filtering, but it does not clarify whether the fiscal years are inclusive, required, or how they interact. The description partially compensates but leaves gaps for the fiscal year parameters.

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 that the tool summarizes an organization's NIH SBIR/STTR award portfolio, specifying the grouping dimensions (core project, fiscal year, activity code, PI) and the target organization. This specific verb+resource+scope distinguishes it from sibling tools like nih_grant_award_history or search_grants, which focus on different aspects of NIH funding 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 provides clear context on when to use the tool (to summarize a specific organization's SBIR/STTR portfolio) and includes important cautions: wildcard-based matching necessitates recipient identity verification, and reported amounts are federal obligations, not revenue. It does not explicitly name alternative tools or state when not to use it, but the context and cautions offer practical 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 are all false and provide no safety/behavior hints, so the description carries the burden. It discloses the rate limit (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that submissions are read in daily digests affecting roadmap. This goes well beyond the annotations and clarifies the write/communication nature 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?

Eight sentences, but each carries distinct information: purpose, categories, scope exclusion, ambiguity resolution, content guidance, and operational limits. It is front-loaded with the core purpose and avoids fluff, though slightly longer than necessary it remains efficient.

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

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

For a feedback tool with no output schema, the description covers all essential aspects: what it does, when to use, what not to include, rate limits, and quota behavior. The nested context object is adequately described in the schema, and the description supplements it with practical usage advice, making it contextually 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful extra semantics by explaining type values (bug, feature, data_gap, praise) and instructing users to frame feedback in terms of Pipeworx tools/packs rather than pasting end-user prompts. This adds value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories and clearly distinguishes this tool from siblings by scoping it to 'tools served by this Pipeworx connection' and explicitly excluding other MCP servers' tools.

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

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

Provides explicit when-to-use guidance: bug (wrong/stale data), feature (missing tool), data_gap (data not exposed), praise (worked well). Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This tells the agent exactly when to invoke and when not to.

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, non-destructive. Description adds valuable context: data derived from CF analytics-engine, no PII, caching behavior (5min-1h). No contradiction with annotations.

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

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

Three concise sentences: purpose, use cases, data provenance/caching. Front-loaded with core action and resource. 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?

Tool is simple (1 param, no output schema). Description explains what is returned (top tools, packs, volume) and caching behavior. Adequate for an agent to use correctly.

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

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

Schema covers the single parameter with enum and description (100% coverage). Description adds interpretative guidance: shorter windows for hotness, longer for steady-state. This adds value beyond the schema.

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

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

The description clearly states it returns top tools, packs, and call volume over a window, with explicit use cases. It distinguishes itself from siblings by focusing on trending agent call data, which is unique among the listed tools.

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

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

Provides three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment) but does not explicitly state when not to use or mention alternative tools for similar purposes.

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 fully aligns with readOnlyHint and idempotentHint, disclosing that it is analytical and non-destructive. It proactively warns about the fill check: realizable_edge_pp ≤ 0 means the arbitrage exists only at last-trade, not in the book, advising not to trade. No annotation contradictions.

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

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

The description is dense and packed with valuable information, but it is presented as a single unstructured paragraph. It could benefit from bullet points or sections (e.g., 'Modes:', 'Response:') for easier parsing by an AI agent. Nonetheless, no sentence is wasted.

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

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

Given the tool has no output schema in the definition, the description thoroughly covers the response structure (opportunities[] with gap_pp, suggested_trade, etc.), includes edge cases (skipped_low_similarity, placeholders_filtered), and warns about the fill check. It is complete for a complex analysis tool.

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

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

Although schema description coverage is 100%, the description adds extensive meaning: it explains accepted formats (slugs or full URLs for 'event', seed questions for 'topic'), describes the offline checks (semantic anchor, partition filter, fill check), and details response structure. This goes well beyond the basic 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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinctively names three operational modes (trending_scan, event, topic) and differentiates from sibling tools by its unique detection methodology.

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 each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic for cross-event scanning'. It also notes that cross-event mode catches patterns single-event misses, providing clear guidance on alternatives.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing the three model families, response segments, diagnostic info, caching, and limitations like Fed market exclusion. 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 and well-organized, front-loading purpose and then detailing models, response, and parameters. Every sentence adds value, though slightly longer than necessary for simpler tools.

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 (multiple model families, 9 parameters, no output schema), the description covers all essential aspects: response structure, diagnostics, edge cases, caching, and parameter interactions. It fully compensates for lack of output schema.

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

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

Schema coverage is 100%, but the description adds substantial value by explaining parameter interactions, default behaviors, and rationale behind each knob (e.g., slippage_pp context, min_partition_leg_kelly behavior). This exceeds the baseline for high coverage.

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

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

The description explicitly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and is built for 'what should I bet on today'. It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven 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?

The description provides clear context for when to use the tool (discovering opportunities without manual browsing) and includes guidance on tradeable-edge knobs and filters. However, it does not explicitly state when not to use it or name alternative tools for different use cases.

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 beyond annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), computed fields (trend, decay_pp_per_day), and limits (TTL, snapshot start). No contradiction with annotations, which are all read-only and safe.

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

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

The description is detailed but well-structured, front-loading the key question. Every sentence adds value, though it could be slightly more compact or use bullet points for the response sections. Still, it is appropriate for the complexity.

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

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

Given the tool's complexity (time series, multiple response categories), the description is thorough. No output schema exists, so the response format is fully explained. Edge cases (gaps, TTL) are covered, making it complete.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: days lookback is clamped 2-30 with default 14, window default '1wk' with possible values listed (24hr, 1mo). Also explains snapshot gaps due to cache-miss behavior.

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, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis and decay trends.

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 by explaining that a 3-week-old wide edge is fundamentally different from a fresh one. Args are described with defaults and limits. However, it could explicitly mention when not to use (e.g., for raw current edges) or point 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 indicate read-only, idempotent, non-destructive behavior. The description adds rich context: walks the ladder, returns specific fields (top_of_book, slippage, verdict), warns about partial basket fills and stranded positions. No contradiction with annotations.

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

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

The description is moderately long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Each sentence adds value, though some technical details could be slightly condensed.

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

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

No output schema, so the description must explain return values—it does so thoroughly for both modes, listing fields and verdicts. Also covers edge cases (thin legs, forced directional risk). Complete for a fill-risk check tool.

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

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

Schema coverage is 100%, but the description significantly enhances understanding: explains the dual-mode (market vs event), defaults for side in basket mode, and different interpretations of size_usd (spend vs target proceeds vs settlement notional). Adds value beyond the schema.

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

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

The description clearly states it checks realizable-vs-theoretical edge against live CLOB order-book depth, distinguishing between single-market and basket modes. It uses specific verbs (check, walk, return) and provides distinct features not found in sibling tools like polymarket_arbitrage or 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 states to use before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. Provides clear context and indicates when it's critical, though it does not state when not to use it explicitly.

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 adds extensive behavioral details: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explicit warnings about pre-mapped topics. 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 detailed and well-structured with sections for modes, response, and safety fields. Every sentence adds necessary information given the tool's complexity, though it 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?

No output schema is provided, but the description adequately explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers key fields and edge cases, making it complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value beyond schema by explaining the behavior of topic vs explicit parameters and providing usage examples. Baseline is 3, but the added 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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers) and distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides explicit guidance on when to use each mode and warns that most pre-mapped topics return compatibility warnings, implying when not to rely on them. It also clarifies conditions for meaningful spreads. However, it does not directly contrast with alternatives like polymarket_edges.

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, covering safety. The description adds valuable behavioral context: scoping to identifier (anonymous IP, BYO key hash, account ID) and pairing with related tools. No contradictions.

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

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

Two sentences with no redundancy. Core action is front-loaded ('Retrieve a value... or list all saved keys'). 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?

For a simple read-only tool with one optional parameter and no output schema needed, the description fully covers purpose, usage, scoping, and relationships to siblings.

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 the single optional parameter. The description adds meaning: 'omit to list all keys' clarifies behavior when key is absent, and examples illustrate typical values.

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

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

The description clearly states the tool retrieves a value saved via `remember` or lists all keys if omitted. The verb 'retrieve' and 'list' are specific, and the resource 'memory' is unambiguous. It distinguishes from sibling tools `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?

Provides explicit context on when to use (look up stored context) and scoping to identifier. Mentions pairing with `remember` and `forget`. Could be improved by explicitly stating when not to use, but overall guidance 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 readOnly, idempotent, non-destructive. Description adds valuable behavioral context: the mark_read flag affects subsequent calls, each alert carries source/citation_uri/payload, and the feed is persisted. 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?

Five sentences, each adding distinct information. Front-loaded with purpose. Some minor inefficiency (e.g., 'pulls... returns...' could be combined) but overall concise for the content conveyed.

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

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

No output schema, so description must explain return values—it does (source, citation_uri, payload). Covers filtering and mark_read. Not fully explicit about limit behavior (though schema defines it) or pagination, but adequate for a simple read 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), so baseline is 3. Description enhances semantics by giving concrete filter examples (e.g., 'sec_8k'), clarifying since as ISO timestamp, and explaining mark_read's effect on next call. This adds 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 the tool pulls recent alerts from the subscription feed. It specifies the resource (alerts from persisted feed) and the action (pull/recent), and distinguishes from siblings like list_subscriptions by focusing on fired events with source, citation_uri, and payload.

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 mentions polling works fine and points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, giving clear context when to use this tool. However, it does not explicitly state when not to use it or contrast with other sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: fans out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and return format with citation URIs. 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 front-loaded with use cases and comprehensive, but somewhat lengthy. Every sentence adds value, though could be more structured. Nearly concise for the complexity.

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

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

Despite no output schema, description explains return structure (changes[] grouped by source, total_changes, citation URIs). Covers all necessary context: multi-source, fallback, soft-fail, and contrasting with 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 coverage is 100% with descriptions. Description adds further context: examples for 'since' (ISO date and relative shorthand with '7d', '30d', '3m', '1y'), and explains 'value' accepts ticker or CIK. Adds 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 it provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO). Distinguishes from sibling entity_profile by specifying when to use each.

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 typical use cases ('What's new with X', etc.) and when not to use (use entity_profile for static profile). Explains fallback behavior between GDELT and GNews, and soft-fail for USPTO.

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

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

Annotations provide idempotentHint=true while description adds critical behavioral details: key-value storage scoped by identifier, persistence differences between authenticated vs. anonymous sessions (permanent vs. 24 hours). No contradictions.

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

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

The description is well-structured and front-loaded with the purpose. Each sentence adds value, though it could be slightly more concise without losing 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 two-parameter tool with no output schema, the description fully covers purpose, usage, behavior, and relevant sibling tools. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions. The description adds examples (e.g., 'subject_property') but does not significantly enrich parameter 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's purpose: 'Save data the agent will need to reuse later'. It provides specific examples (resolved ticker, target address, user preference) and distinguishes it from sibling tools like recall and forget.

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

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

The description explicitly states when to use: 'Use when you discover something worth carrying forward'. It also explains scoping and persistence, but lacks an explicit 'when not to use' statement. However, it pairs well with recall and forget.

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 beyond that: it reveals internal cascading through multiple endpoints, auto-disambiguation of inputs, and specific output details including citation URIs. This gives a fuller behavioral picture 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 moderately long but well-structured and front-loaded with real user queries. Every sentence adds value, covering purpose, supported types, output specifics, and internal behavior. It is denser than minimal, but the complexity of two entity types justifies the length.

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

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

Given the tool's complexity (two entity types, distinct outputs, no output schema), the description adequately covers return values for each type, including citation URIs, and explains the internal multi-lookup behavior. It also positions the tool within the broader workflow ('replaces 2-3 manual lookups'). Some minor gaps exist, like no explicit error handling or output format example, but 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?

The input schema already provides 100% coverage with clear enums and examples. The description builds on this by specifying what each type returns and noting that the value parameter is auto-disambiguated, adding meaning beyond the schema. Since the schema does much of the work, but the description enriches parameter understanding, this is slightly above baseline.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical official identifiers. It uses specific verbs like 'resolve' and 'look up,' provides concrete example queries, and explicitly lists supported types (company, drug) with their respective output fields. This distinguishes it from sibling tools that operate on already-resolved 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 says 'Use FIRST whenever you have a name but need an ID,' providing a clear directive. It also implies when not to use it ('other tools require as input'), indicating that if you already have the ID, this tool is unnecessary. This is strong, actionable guidance relative to alternatives.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, treats first entity as subject, and returns ranked list with score, confidence, signal density. No contradictions.

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

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

The description is concise with two sentences and a list of returned fields. It is front-loaded with the main action and contains no unnecessary words.

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

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

Given the tool's complexity (4 parameters, no output schema), the description explains the return fields (score, confidence, signal density) and overall behavior. However, it does not elaborate on exact output format or score interpretation, which would be helpful.

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%, providing baseline of 3. The description adds semantic value by clarifying the relationship between entities (first as subject) and the 'context' parameter's role in disambiguation, as well as explaining the 'models' parameter choices.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probe, rank, surface) and resource (AI presence across entities). It differentiates from sibling 'compare_entities' by focusing on AI visibility and mentioning 'ai_visibility_check' probes.

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 usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use but does not explicitly state when not to use or compare to alternative tools like 'compare_entities' or 'ai_visibility_check'.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses internal fan-out to deps.dev and bundlephobia, performance edge case (bundlephobia first measurement 5-30s), and graceful degradation with 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 a single paragraph but well-structured: purpose first, then usage, return format, scope, and edge cases. Each sentence adds value, but it could be more scannable with bullet points. Still efficient 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?

Even without an output schema, the description lists all return fields (summary block with 8 fields, per-advisory detail, links, alternative versions). It covers ecosystem limitation, partial failures, and performance caveat. A comprehensive description for a composite 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. The description adds context: scoped packages accepted for 'package', and version defaults to latest. This is extra value beyond the schema, justifying a score above 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 starts with a clear verb and resource: 'Composite should I add this npm package to my project check'. It explicitly states the composite nature and the specific services queried. The tool name 'scan_dependency' is well-defined and distinct from sibling tools like 'deep_research' or 'validate_claim'.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies ecosystem limitation ('NPM ecosystem only in v1') and directs other ecosystems to a different method. Mentions partial failure behavior and sources_failed.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive, which the description does not contradict. The description adds that it matches title/abstract/terms and returns specific fields, exceeding annotation info.

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, immediately stating the purpose and listing key features. No unnecessary words, efficiently conveying essential 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?

Covers inputs, filters, and outputs (return fields). Examples are provided in schema. Could mention how filters combine, but overall complete for a search tool with no required 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?

Schema description coverage is 100%, so baseline is 3. The description repeats schema parameter info without adding new details; for example, the query parameter description matches the schema exactly.

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 NIH-funded research projects, specifies the resources (title/abstract/terms, PI, etc.), and distinguishes from siblings like search_publications by focusing on NIH grants.

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 all filter options, providing clear context for when to use it (searching NIH grants). However, no explicit when-not or alternative tools are mentioned, though sibling tools imply different domains.

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, covering safety and idempotency. The description adds minimal behavioral context beyond reiterating the search purpose. 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 two sentences, front-loaded with the purpose, and contains no filler. Every word serves a 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?

Given the rich annotations and schema (including output schema), the description is adequately complete. It covers the primary purpose and use case, though it could mention pagination behavior (but schema already covers limit and offset).

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

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

Schema coverage is 100%, with each parameter described. The description mentions the three filter types (PMID, appl_id, core_project_nums) as in the schema, but does not add new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'search' and the resource 'publications acknowledging NIH funding'. It lists specific filters (PMID, application ID, core project number) and provides a use case ('what came out of this grant' follow-ups), distinguishing it from siblings like search_grants.

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 provides a use context ('useful for follow-ups') and mentions the filtering options. While it does not directly name alternatives, the sibling tools (e.g., search_grants) are listed in context, making the usage guidance clear enough.

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

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

The description adds significant behavioral context beyond the annotations, such as: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and has a 200K char cap with truncation flag. Annotations already indicate safety and idempotency.

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 efficient and well-structured. It starts with the core purpose, then usage guidelines, and ends with technical details. Every sentence contributes useful information without redundancy.

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

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

Given the complexity of the tool (semantic search with vector embeddings) and the absence of an output schema, the description comprehensively explains the return format (passages with offsets and scores) and technical details (embedding model, window size, truncation). It provides sufficient information 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?

Schema coverage is 100% with descriptions, so baseline is 3. The description adds value by providing examples for the query parameter and clarifying the max length for text. This extra context justifies a score of 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 it performs semantic search inside a fetched record, using a natural-language query, and returns top-N passages. It distinguishes itself from siblings by explicitly mentioning it pairs with ask_pipeworx_grounded and contrasts with fetching the whole document.

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 when-to-use guidance: when the record is too big to fit into the prompt. It mentions an alternative (ask_pipeworx_grounded). However, it does not explicitly state when not to use it, 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?

Adds significant behavioral context beyond annotations: required OAuth account, delivery channel details, rate limits for SMS, webhook auto-disable after 10 failures, and type-specific constraints. Annotations already indicate idempotent, non-destructive, and write operation, which is consistent.

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 clear sections, bullet points, and examples. Every sentence adds value; no redundancy. Front-loaded with the main 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?

Despite no output schema, description explains the return value (subscription id). Addresses prerequisites, supported types, and delivery channels comprehensively. Distinguishes from sibling subscription management 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 coverage is 100% and description enriches each parameter with concrete examples and usage details (e.g., sec_8k items codes, polymarket_edge topics, delivery verification). Provides meaning well beyond the schema definitions.

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

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

Explicitly states it creates a subscription to a live-data event stream and returns the new subscription id. Differentiates from sibling tools 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?

Provides clear context for when to use (proactive monitoring) and requirements (OAuth account). Mentions that anonymous/BYO cannot persist. Does not explicitly list when not to use, but sibling tools 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond these, explaining it returns example questions drawn from a live catalog and that it's an onboarding tool. No contradictions.

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

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

The description is relatively long but front-loaded with key purpose and usage. It uses bullet-like lists and examples. Every sentence adds value, though it could be slightly more concise 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?

Given the tool's simplicity (1 optional param, no output schema) and context of being an onboarding tool, the description fully covers what the tool returns and when to use it. It compensates well for the lack of an output schema by describing the output structure.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the optional 'topic' parameter provides focus areas like 'finance' or 'pharma' and that omitting it gives a full spread. This enriches the schema's basic string description.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx and entity_profile by positioning it as the 'what can I ask' starter.

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

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

The description explicitly states when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with or without the topic argument. It effectively directs the agent to use this tool before other meta-tools.

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

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

Adds meaningful context beyond annotations: ownership enforcement, deactivation (not deletion), and connection to 'recent_alerts'. Annotations already cover idempotency and non-destructiveness, so 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?

Two sentences with zero waste. Front-loaded with action and resource, followed by critical constraints and side-effects.

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?

Complete for a simple one-parameter tool without output schema. Covers purpose, constraints, and what happens to data (deactivation) and where to find historical events.

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?

Parameter 'id' is fully documented in schema with source ('returned by subscribe'). Description does not add additional semantics, but schema coverage is 100%, so 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?

Explicit verb 'Cancel' and resource 'a subscription by id'. Clearly differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by stating side-effect (deactivation) and linking to '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?

States ownership enforcement (only cancel own subscriptions) and that the row is deactivated, not deleted, giving clear context. Does not explicitly state when not to use, but the guidance is sufficient for 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: internal routing logic, return values including verdict, actual value with citation, and reasoning. 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 informative paragraph, front-loaded with purpose and examples. It contains no wasted words, though it could be slightly more structured for readability.

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 explains return values: verdict options, actual value with citation, and reasoning. For a tool replacing multiple calls, it provides complete context for agent invocation.

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

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

Schema coverage is 100% with both parameters well described. The description reinforces usage with examples and default behavior for tolerance_pct, but adds limited new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It distinguishes itself by noting it replaces 4-6 sequential calls and handles company-financial claims differently from other facts, setting it apart 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples and differentiates between structured SEC path and grounded pipeline. However, it does not explicitly mention when not to use the tool or compare with specific alternatives among siblings.

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