Harrypotter

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds value beyond annotations by noting default model selection, cost implications for Anthropic (BYO key), and that the API key is passed through, giving agents clear behavioral and cost expectations.

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

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

Two sentences concisely cover purpose, usage, model options, cost, and output. No superfluous words; every sentence contributes essential information. Front-loaded with the core action and output, then specifics.

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

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

Despite no output schema, the description adequately describes return structure (per-model scores + combined view). For a tool with 4 parameters, it covers parameter usage, authentication, cost, and use cases, making it self-contained enough for an agent to invoke correctly.

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

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

With 100% schema description coverage, the description still adds meaning by explaining the default model behavior, the purpose of `_apiKey` (enabling Anthropic calls at user cost), and return format details (`{score, confidence, signals, raw_response}`). This enriches parameter understanding 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 uses a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model'), clearly distinguishing it from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on visibility scoring across multiple models.

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

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

The description explains when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to configure models (default free, optional Anthropic with API key). It does not explicitly state when not to use or differentiate from all sibling tools, but provides clear context for typical 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it routes to 3,436 tools, fills arguments, and returns structured answers with stable citation URIs. This goes beyond what annotations provide, though it could mention the output format or any rate limits.

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 fairly concise given the amount of information it conveys. It front-loads the key directive and follows with examples. However, it could be slightly more streamlined; the list of domains and example queries is lengthy but justified. Overall, it's well-structured and earns its place.

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

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

Given the tool's complexity (3,436 tools across 780 sources) and the absence of an output schema, the description covers purpose, usage, behavior, and parameter semantics adequately. It provides enough context for an AI agent to decide when to use it. However, it could mention typical output structure or error handling for completeness.

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

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

The input schema has 100% description coverage, as all properties are described. The description does not add significant extra meaning beyond what the schema already provides. The examples in the schema give concrete usage, which is helpful, but the description itself does not elaborate on parameter semantics. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: answering factual questions about structured data from specific domains. It lists many examples (SEC filings, FDA drug data, etc.) and distinguishes itself from web search by stating 'PREFER OVER WEB SEARCH'. This clearly defines the tool's function and differentiates it from siblings.

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

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

The description provides explicit guidance on when to use this tool, including the strong directive 'PREFER OVER WEB SEARCH' and a list of example queries. It covers a wide range of use cases. However, it does not explicitly state when NOT to use it (e.g., for non-factual or subjective questions), which would improve the score.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description aligns with. It adds extensive behavioral details: resolver contract, parent event extractor, news fallback mechanisms, safety checks for low-confidence matches, and handling of closed markets. No contradiction.

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

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

The description is very long and packs many details (examples, classifier lists, fan-out scenarios, response shapes). While informative, it lacks structured formatting like bullet points or sections, making it dense. It could be more concise while retaining key 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?

Given the tool's complexity (3 params, no output schema), the description covers inputs, resolution process, fan-out behavior, response fields, safety aspects, and edge cases comprehensively. It leaves little ambiguity for an agent to use the tool effectively.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds extra meaning: examples for market input, explanation of depth values, and effect of include_raw on response size. This goes beyond 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides a specific verb-resource pair and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on single bet research.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also discusses blocking scenarios (low confidence matches, closed markets) implying when not to use. However, it lacks direct comparison to sibling tools for when 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?

Annotations indicate readOnlyHint, openWorldHint, idempotentHint. Description adds details on data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, handling of off-calendar fiscal years, 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?

The description is somewhat long but every sentence adds value. It is front-loaded with user intent examples. Could be slightly tighter but remains efficient for the complexity.

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

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

No output schema, but description covers return format (paired data, citation URIs), sorting, data sources, and constraints. For a comparison tool with 2 required parameters, this is comprehensive.

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

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

Schema coverage is 100%. Description explains the 'type' parameter with details on what each entity type retrieves (financials vs. adverse events/trials) and the 'values' parameter with examples and constraints (2-5 items). Adds significant meaning beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs in one parallel call. It lists example queries and data sources, and distinguishes from sibling tools like entity_profile and resolve_entity which are for single entities.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example queries. While it doesn't list exclusions, the context for when to use is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include 'names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly', but does not contradict annotations. Added context is useful but not extensive.

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 one concise paragraph that front-loads the purpose and includes all necessary information. No wasted sentences, though a bulleted list might improve scannability.

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 discovery role and many siblings, the description adequately covers purpose, usage, return content, and when to call. No output schema, but explanation of returned data is sufficient.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add new parameter meaning beyond noting 'top-N' and default/max limit, which is already in 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 verb 'Find tools' and the resource 'by describing the data or task'. It lists specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself from siblings with 'Call this FIRST'.

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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST...' It implies that for direct answers, other tools are appropriate, though it does not name 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 details data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), return fields (CIK, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset warning, news fallback, LEI). This provides behavioral context beyond annotations, which are generic.

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 that front-loads purpose and usage guidance, then details return data. It is densely informative but could benefit from more structured formatting (e.g., bullet points) 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 specifies the response structure: what fields are returned, their sources, formatting (URIs, sorted fundamentals), and limitations (patents soft-fail). This provides sufficient context for an agent to process results.

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

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

Schema has 100% coverage with parameter descriptions. The description adds valuable examples ('AAPL', '0000320193') and clarifies that names are not supported, directing to resolve_entity. This improves parameter semantics 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 defines the tool as generating a full cross-source profile of a US public company, using specific user query examples. It distinguishes from sibling tools by explicitly stating preference over chaining single-purpose lookups and noting when to use resolve_entity first.

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 (holistic view) and when not (name-only queries, directing to resolve_entity). Provides a clear directive to prefer this tool over chaining multiple single-source lookups.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context by specifying 'clear sensitive data,' which explains the destructive nature beyond the annotations. No contradictions.

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

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

Two concise sentences. The first sentence states the action, the second provides usage context. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, when to use, and pairing with siblings completely. No missing information.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete.' The description adds no additional meaning beyond this, so baseline score of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies the verb (Delete), resource (previously stored memory), and identifier (key). This distinguishes it from siblings like 'remember' and 'recall' which are mentioned for pairing.

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also instructs to 'Pair with remember and recall,' providing explicit when-to-use and alternative 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?

Description adds valuable behavioral context beyond annotations: fetches page, extracts content, emits standard markdown. Annotations already indicate read-only, idempotent, open-world, non-destructive. No contradictions. Description enriches understanding.

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

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

Two tightly written sentences plus a brief bullet list of use cases. Front-loaded with action and purpose. No wasted words; every sentence contributes to understanding.

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

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

For a simple tool with two parameters and plain text output, description covers all essentials: what it does, how it works, output format, and use cases. No output schema needed since output is described clearly.

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 for both parameters. Description adds default and max for max_links, but this is minor. Schema already does the heavy lifting, so description adds marginal value. 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?

Clearly states the tool generates an llms.txt file for a URL, lists what it extracts (title, description, key links), and specifies output format. Distinguishes from sibling tools by being the only one dedicated to llms.txt generation.

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

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

Provides explicit use cases (getting client's site indexed, drafting for own project, auditing competitors). Does not explicitly exclude or name alternatives, but context is clear. Sibling tools like scan_competitor_ai_presence are different, so confusion is unlikely.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description adds minimal behavioral context beyond confirming it is a listing operation. 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: one for purpose and one for optional filters. No extraneous words; 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?

The description covers purpose and filters, but lacks information about the return format (e.g., fields returned per character). For a simple list tool without an output schema, this gap reduces completeness.

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

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

Schema coverage is 100% and the description re-iterates the same information for 'house' and 'search' parameters. No additional semantic value beyond what the schema already provides.

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

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

The description clearly states the tool lists Harry Potter characters and specifies the scope (wizards, witches, other figures). It is distinct from sibling tools like list_students and list_staff by covering all character types.

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

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

No guidance on when to use this tool over listed sibling tools such as list_students or list_staff. The description only covers optional filters, not decision criteria for tool selection.

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, open-world, idempotent, and non-destructive. The description adds minimal behavioral context beyond the purpose; it does not contradict annotations.

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

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

Two concise sentences cover the main purpose and optional filter with no wasted words.

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

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

For a simple list tool with one optional parameter and rich annotations, the description adequately conveys the functionality. It does not detail output format but that is not critical given the simplicity.

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 parameter description already explains the filter behavior. The tool description only restates the filter option without adding new 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 lists Harry Potter spells with their effects and optionally filters by name. It is distinct from sibling tools that list other 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 mentions optional filtering but provides no explicit guidance on when to use or not use this tool versus alternatives. Usage is implied but not elaborated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds minimal behavioral context beyond stating that it lists 'all' staff, which is a scope clarification.

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

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

A single sentence that is front-loaded with the verb and resource, containing no filler words or unnecessary information.

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

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

The tool has no output schema and the description does not specify output format or fields, which would be beneficial. However, for a simple list tool with no parameters, it is minimally adequate.

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?

No parameters are defined, and the description confirms no filtering options. With zero parameters, baseline is 4; the description does not add parameter-specific meaning but aligns with the schema.

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

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

The description uses a specific verb 'list' and identifies the resource as 'all Hogwarts staff (professors and other employees)' from a well-known universe, clearly distinguishing it from siblings like list_characters and list_students.

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 via the purpose but provides no explicit guidance on when to use this tool over alternatives or mention of context like prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds no extra behavioral details (e.g., pagination, authentication), which is acceptable given the annotations, but does not go beyond them.

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

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

The description is a single, well-structured sentence with no extraneous words. It is perfectly concise and front-loaded.

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

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

For a simple tool with no output schema, the description is minimal. While it indicates what the tool returns ('list of students'), it does not describe the structure or fields of each student object, which could leave the agent uncertain about the response format.

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?

No parameters exist, so the input schema has full coverage. With zero parameters, the baseline is 4 per rubric. The description does not need to add parameter semantics.

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

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

The description clearly states the tool's action ('List'), resource ('all Hogwarts students'), and scope ('from the Harry Potter universe'). It is concise and specific, distinguishing it from sibling tools like 'list_characters' and 'list_staff'.

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 no guidance on when to use this tool versus alternatives such as 'list_characters' or 'list_staff'. It merely states what it does, missing explicit context or exclusions.

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

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

Annotations do not contradict the description. The description adds behavioral context beyond annotations: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' This informs the agent of side effects and constraints.

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

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

The description is three sentences with no wasted words. It front-loads the purpose, then usage guidelines, then behavioral notes. 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?

Given the simplicity of the tool (feedback submission) and no output schema, the description covers all necessary aspects: purpose, when to use, what to include, restrictions, and rate limits. It is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing usage context for parameters, e.g., 'Describe the issue in terms of Pipeworx tools/packs' for the message parameter, and the enum descriptions in the schema are already thorough.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes this tool from sibling tools by being the only feedback channel.

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 feedback type: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises what not to do ('don't paste the end-user's prompt') and mentions rate limits.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: derived from CF analytics-engine, no PII, only counts of (pack, tool), and caching behavior (5min-1h). No contradiction.

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

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

The description is concise (four sentences) with key information front-loaded. Every sentence adds value, from purpose to use cases to caching behavior.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, use cases, behavioral traits, and caching, leaving no gaps.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds usage guidance on window choice (shorter for hot vs longer for steady-state), providing value beyond the schema enum.

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, top packs, and total call volume' and specifies the resource (Pipeworx trending data). It distinguishes itself from siblings by explaining it is a 'self-aggregating signal' derived from analytics.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming popular tool, checking alignment). It provides context for when to use the tool, though it does not explicitly say when not to use or mention 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?

Discloses internal logic (monotonicity, partition checks), semantic anchor requirement, partition filter, and failure conditions. Adds significant context beyond annotations which already indicate safe, idempotent behavior.

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

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

Somewhat verbose but all content valuable. Front-loaded with requirement warning, then modes, then technical details. Could be slightly more structured but remains clear for an AI agent.

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?

Comprehensive coverage: explains response structure, edge cases with placeholder slugs, semantic similarity thresholds, and both event and topic modes in detail. No output schema, so description fully covers return values.

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?

Both parameters have descriptions in schema; description adds example values, mode-specific behavior, and clarifies acceptance of full Polymarket URLs. Meaningfully enriches parameter understanding.

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

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

Clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing event and topic modes. Differentiates from siblings like polymarket_edges and polymarket_kalshi_spread.

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 requires one of event or topic, warns against no args, recommends event for specific markets and topic for cross-event scanning. Lacks explicit alternative tool exclusions but provides clear usage context.

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

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

The description extensively discloses behavioral traits beyond the annotations (readOnlyHint, idempotentHint, etc.). It details caching (1h KV-level keyed on all knobs), response structure (three segments under by_segment, fed_candidates, diagnostics), filtering logic (placeholder-slug filter, partition >20% placeholder skipped), and edge calculation components (edge_pp_net, Kelly fractions, slippage, liquidity, spread, 24h move warning). This provides rich context for an agent to understand exactly what the tool does and its limitations.

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

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

The description is very long and packed with technical details, which can be overwhelming. It is front-loaded with the main purpose, but the dense technical exposition (e.g., detailed explanations of edge calculations and model families) could be more concise. The structure uses segment headings (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) which helps, but overall it lacks brevity.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers the response structure in detail (by_segment, fed_candidates, _diagnostics) and explains the diagnostics so callers can understand empty segments. It also mentions caching behavior. However, it could be more explicit about the meaning of edge_pp_net and other fields in the response, though these are mentioned in passing. Overall, it is sufficiently complete 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 description coverage is 100%, so baseline is 3. The description adds valuable context beyond the schema: it explains the rationale for default values (e.g., slippage_pp default 0.3 with explanation of Polymarket fees), distinguishes between similar parameters (min_kelly vs min_partition_leg_kelly), and groups parameters (tradeable-edge knobs). This enhances understanding but is not essential since schema already covers them.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('Scan', 'return') and identifies the resource ('Polymarket markets'). It distinguishes from sibling tools like 'polymarket_arbitrage' and 'polymarket_kalshi_spread' by focusing on data disagreement, making its unique role evident.

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

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

The description is built around the use case 'what should I bet on today', providing clear context for when to use it. It mentions that it saves agents from paging through hundreds of markets. However, it lacks explicit guidance on when NOT to use it or when to prefer sibling tools. The presence of sibling tools implies alternatives but no direct exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read operations. The description goes beyond by detailing the response structure, including safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type, explaining what they mean and when spreads are meaningful. This adds significant behavioral context.

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

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

The description is thorough but not overly verbose. It is well-structured with sections for purpose, modes, response, and safety fields. It front-loads the key purpose. While slightly lengthy, every sentence serves a purpose, and the structure aids 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?

Given the tool's complexity (cross-venue, multiple modes, safety fields) and the absence of an output schema, the description provides comprehensive details about the response, including leg-by-leg prices, spread calculation, compatibility_warning conditions, temporal alignment, and skipped_cross_type explanations. This fully compensates for the missing 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 description coverage is 100%, so parameters are already documented. The description adds value by listing the 10 pre-mapped topic shortcuts and providing examples for explicit parameters (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). It also explains how parameters interact, such as overriding the topic-mapped side.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb 'spread' and resources, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges. The two modes (topic and explicit pairings) further clarify its functionality.

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

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

The description explicitly explains when to use the tool: for comparing spreads between Kalshi and Polymarket. It provides context on the two modes and includes a warning that most pre-mapped topics return compatibility_warning, advising caution. However, it does not explicitly name alternative tools for single-venue analysis.

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 context: 'scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and pairs with remember/forget.

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

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

Two sentences, no wasted words. Front-loaded with primary action. Structurally 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?

Describes retrieval and listing, scoping, and pairing with siblings. No output schema but purpose is straightforward. Sufficient 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 already describes the key parameter (100% coverage). Description adds explanation of omitting key to list all, and concrete usage examples (ticker, address, notes).

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?

Completely clear: 'retrieve a value previously saved via remember, or list all saved keys'. Explicitly distinguishes from siblings '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?

States when to use: 'look up context the agent stored earlier... without re-deriving it'. Suggests omitting key to list all. Could explicitly mention not to use for saving/deleting but context makes it 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details beyond these, such as fan-out to multiple APIs, fallback mechanisms, soft-fail for USPTO until reactivation, and accepted `since` formats (ISO date or relative shorthand). No contradictions with annotations.

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

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

The description is concise despite being information-dense, front-loading usage examples like '"What's new with X" / "latest on Y".' It efficiently packs details about fan-out, fallbacks, and alternatives into a single paragraph without unnecessary 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?

For a 3-param tool with full schema coverage and no output schema, the description provides complete context: input formats, source behaviors, return structure (grouped by source, total_changes count, citation URIs), and clear sibling differentiation. The tool's complexity (multiple API calls, fallbacks) is well-communicated.

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 descriptions for all three parameters (100% coverage). The description adds value by explaining `since` options in detail ('ISO date or relative shorthand like 7d, 30d, 3m, 1y') and recommending '30d' or '1m' for typical monitoring, and clarifying `value` as ticker or CIK. This goes beyond the schema.

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

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

The description clearly states it provides a change feed for a company, covering 'what's new' with examples like 'latest on Y' and 'news on Tesla recently.' It specifies multiple data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling tool `entity_profile`, which returns static profiles.

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

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

The description explicitly tells when to use this tool versus alternatives, stating 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also guides on fallback logic (GDELT preferred, GNews when rate-limited).

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 write, idempotent, non-destructive. Description adds context: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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, front-loaded with core purpose. No extraneous words, every sentence adds value.

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

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

No output schema needed for a store operation. All essential information about key-value, persistence, scoping, and sibling tools is present.

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

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

Schema covers 100% of parameters with descriptions. But description adds naming conventions (e.g., "subject_property") and clarifies value as any text, plus pairs with recall/forget.

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 saves data for reuse across sessions, with specific examples like resolved tickers and user preferences. It distinguishes from siblings 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?

Explicitly advises when to use (discover something worth carrying forward) and pairs with recall/forget for retrieval/deletion. Also mentions scoping by identifier and session persistence.

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 that it cascades through several lookup endpoints internally, which is useful behavioral context beyond annotations. It does not mention any side effects or rate limits, but annotations cover safety.

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

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

The description is front-loaded with examples and is relatively concise given the amount of information. Every sentence adds value, though it could be slightly shorter without losing clarity.

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

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

Despite no output schema, the description explains return values (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It adequately covers the tool's behavior and distinguishes from the many sibling 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%, so baseline is 3. The description adds meaningful context: explains that type is 'company' or 'drug', and value can be various input formats (ticker, CIK, name). It also mentions auto-disambiguation and citation URIs, which go 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 that the tool resolves user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, RxCUI) and supported types (company, drug). It differentiates from siblings by advising to use it first when a name is available but an ID is needed.

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

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

Explicitly states when to use (when you have a name but need an ID) and provides trigger phrases. Also notes that each call replaces 2-3 manual lookups, giving clear context for its application.

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

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

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

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

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

The description is 3-4 sentences, front-loaded with the main function, followed by mechanics, use case, and return type. Every sentence adds value with no wasted words.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It covers constraints (2-8 entities, first as subject), mentions the probing tool, and provides a use case. No gaps remain for an agent to understand 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 has 100% description coverage. The description adds semantic value beyond the schema: it explains that the first entity in the array is treated as the 'subject' for narrative and the rest as competitors, and it notes the default model if omitted. This enriches parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and surfaces most/least recognized. It gives a concrete use case example ('does Claude know about us as well as our competitors?'), and distinguishes itself from sibling tools by being a comparative wrapper.

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 'Useful for competitive AI-marketing audits' and provides an example scenario. It mentions it probes each entity with ai_visibility_check, implying the alternative tool for single entity checks. However, it does not explicitly state when not to use or list exclusions.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement may timeout (5-30s), and sources_failed field. 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 informative but slightly verbose. Front-loaded with purpose, then details. Every sentence adds value, but could be more concise by separating usage guidelines. Still well-structured.

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

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

Given no output schema, description thoroughly explains return structure (summary block, per-advisory, links, alternatives) and notes ecosystem limitation (NPM only in v1). Handles partial failures and timeouts. Complete for agent decision-making.

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. Description does not add new semantics beyond schema: package is npm scoped names allowed, version defaults to latest. No extra parameter meaning provided.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, combining deps.dev and bundlephobia data. It explicitly distinguishes from sibling tools like deps.dev:version for other ecosystems.

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?

Describes when to use (is X safe/popular/small, cost of adding) and explicitly when not to use (PyPI/Maven/Cargo/Go fall under deps.dev:version). Provides clear context and alternatives.

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

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

Annotations already declare safe, non-destructive behavior. The description adds value by detailing the return types (verdict, structured form, citation, percent delta) and noting it replaces 4-6 sequential calls, which no annotation provides.

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 informative and well-structured, starting with trigger phrases. It is slightly verbose but every sentence adds value, with no redundancy.

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

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

Given the single parameter and lack of output schema, the description thoroughly covers purpose, usage, output format, and scope. Annotations provide safety profile. No missing context for effective use.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter. The tool description goes further by explaining the supported claim type (company-financial) and examples, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides explicit trigger phrases like 'fact check' and specifies the scope (company-financial claims). No sibling tool duplicates this function.

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,' providing clear when-to-use guidance. It does not explicitly state when not to use, but the scope limitation is implied.

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