Macvendors

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

Annotations already mark the tool as readOnly, idempotent, and openWorld. The description adds value by disclosing the default free model, the need for a BYO Anthropic key, and the per-model return structure. It does not contradict annotations and provides context about payment responsibility.

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

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

The description is two sentences, front-loaded with the core purpose, and includes essential details on models and return format without unnecessary words. Every sentence provides value.

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

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

Given the tool has 4 parameters, no output schema, and annotations provide safety, the description covers purpose, usage, parameters, and return format. It lacks detail on score computation and error handling, but overall is sufficient for tool selection and invocation.

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

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

Schema coverage is 100% (baseline 3). The description enriches parameters by noting the default for 'models', the conditional nature of '_apiKey', and the disambiguation role of 'context'. It adds meaningful context beyond 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 probes LLMs for knowledge about an entity and scores visibility per model. It uniquely distinguishes itself from sibling tools (e.g., no other 'probe' or 'visibility' tool) and specifies the range and return format.

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

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

The description provides explicit use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', but does not explicitly state when not to use it or compare with sibling tools like 'scan_competitor_ai_presence'. However, the use cases are clear and actionable.

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

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

Annotations already declare readOnly, openWorld, idempotent; description adds context about routing to 3,567 tools and returning structured answers with citation URIs, enhancing 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?

Front-loaded with key instruction to prefer over web search, followed by clear purpose and examples; slightly verbose but each 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?

Provides thorough explanation of tool's function, use cases, and output format (structured answers with citations); lacks mention of error handling or limitations for unmappable queries.

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 all parameters; description adds examples and context but does not significantly expand on parameter semantics beyond what schema 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?

Description clearly states it routes questions to a vast set of tools for factual data, with explicit preference over web search, specific verb 'ask' and resource 'pipeworx', and distinguishes by providing examples of use cases.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists query types and example questions, but does not mention alternatives among sibling tools like 'ask_pipeworx_grounded'.

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 explains that it costs one extra LLM call, details the return format (success with answer/evidence/confidence/source/fetched_at, or refusal with refusal_reason), and lists explicit refusal reasons. This adds substantial behavioral context beyond the annotations, which already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. 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-loads the key purpose and use case. Every sentence adds value, explaining behavior, trade-offs, return format, and refusal reasons. It could be slightly trimmed but is 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 the complexity (3,567 tools across 828 sources), the description is highly complete: it explains routing, extraction, return structure, refusal reasons, cost trade-off, and differentiates from sibling. No output schema exists, but the description covers return format sufficiently.

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% (all 6 parameters are described in the schema). The description does not add new information about the parameters beyond what the schema provides, 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?

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process: routing, filling arguments, fetching data, then extracting answer only from tool result. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call and use case for high-stakes reads.

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

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

The description explicitly says to use 'whenever an answer will be quoted, cited, or acted on' and prefers 'ask_pipeworx for casual lookups'. It lists specific scenarios (financial verdicts, legal claims, etc.) and names the alternative tool, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing resolution confidence levels (high/medium/low/none), safety mechanisms (low-confidence matches short-circuit), behaviors for closed/dead markets, wide-spread warnings, and fallback logic for news sources (GDELT 429s). This is exceptionally comprehensive and adds significant value beyond the annotations.

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

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

The description is very long (700+ words) and dense, which is partly justified by the tool's complexity. It is well-structured with labeled sections (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and front-loaded with the core purpose. However, it could be more concise without losing critical information—some details (e.g., specific Fred series codes) might be better placed in the schema or separate documentation.

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 parameters, no output schema, extensive fan-out logic), the description provides comprehensive context: resolver contract, parent event extractor, news fallback fields, safety measures, and blocking behaviors for closed markets. It leaves almost no question about what the tool returns and how it behaves in edge cases.

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

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

Schema description coverage is 100%. The description adds meaningful context for each parameter: market input examples (slug, URL, text), depth default behavior, and include_raw recommendation with size implications. Examples in the schema are complemented by detailed fan-out illustrations in the description, making parameter semantics exceptionally clear.

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 researches a Polymarket bet by pulling Pipeworx data, explicitly listing three input types (slug, URL, question text) and multiple classifiers. It directly addresses use cases like 'should I bet on X' or 'is there edge in Z', which distinguishes it from sibling tools like polymarket_edges (which focuses on edge detection) and polymarket_arbitrage (which focuses on spreads).

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 ('Use for...') with concrete examples. However, it does not mention when not to use it or suggest alternative sibling tools for related tasks (e.g., polymarket_edges for edge calculation only). This omission prevents the agent from fully understanding the tool's boundary.

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. Description adds context about data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph with all key information front-loaded. While every sentence adds value, it could be slightly more structured (e.g., bullet points). Still, it is appropriately sized 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?

Covers purpose, usage, parameters, and behavioral details. Mentions return format (paired data + citation URIs). Lacks explicit mention of error handling, but overall complete given complexity and annotations. No output schema but description compensates.

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%, but description adds significant meaning: explains data sources for each type, provides format examples for values (tickers/CIKs vs drug names), and clarifies sorting 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 does side-by-side comparison of 2–5 companies or drugs. It uses specific verbs like "compare" and provides example queries. It distinguishes from siblings by stating it should be preferred over sequential single-pack lookups.

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

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

Explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also gives specific examples of natural language inputs and explains sorting behavior for 'largest/most' queries.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: returns top-N tools with schemas and curated examples, ready to call directly, and no second lookup needed. No contradiction exists.

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 plus a bullet list of domains. It is front-loaded with the main purpose. The list is slightly lengthy but still clear. No wasted words.

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

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

Given the tool's simplicity (6 parameters, no output schema needed), the description covers purpose, usage context, output behavior, and example queries. It is complete for an AI agent to decide when and how 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% (all parameters have descriptions). The description does not add significant meaning beyond the schema for parameters like query and limit. Baseline score of 3 applies as the schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and specifies the output structure. The instruction 'Call this FIRST' distinguishes it 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 states when to use it: 'when you need to browse, search, look up, or discover what tools exist for' and lists specific domains. It advises calling it first when many tools are available, implying not to use it if you already know the tool. However, it does not name alternative tools for specific 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. The description adds transparency by detailing the data sources (SEC, XBRL, USPTO, news, GLEIF), output structure, and a known sunset issue (USPTO API). 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 well-structured with examples, preferred usage, return details, and input format. It is front-loaded with critical guidance. Slight verbosity but all content is 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 complexity of a multi-source profile tool, the description covers input constraints, data sources, return fields (including URIs), and a known limitation. No output schema exists, so the description adequately provides return semantics.

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 usage context: 'type' only supports 'company', 'value' accepts ticker or CIK but not names. This adds meaning beyond the schema enum and type 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 provides a 'full cross-source profile of a US public company' with examples like 'Tell me about X' and 'research Acme'. It distinguishes from sibling tools such as resolve_entity by noting that names are not supported.

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 chaining single-pack lookups when the user asks for a holistic view' and instructs to use resolve_entity first for names. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' but no additional behavioral details beyond confirming deletion.

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 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?

For a simple, single-parameter tool with annotations present, description covers purpose, usage context, and sibling relationships. Missing details on return value or error handling, but acceptable given 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% with a single 'key' parameter described as 'Memory key to delete.' Description adds no extra 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?

Description starts with 'Delete a previously stored memory by key,' a specific verb+resource combination. It also distinguishes from siblings by referencing 'remember' and 'recall.'

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Provides sibling context but no exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., indicating safe operations. The description adds detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which goes beyond annotations by describing internal steps.

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 with minimal waste. The first sentence states the core function and output; the second lists use cases. Every part 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 simplicity (2 params, no output schema, full annotations), the description adequately explains the output format and process. It could mention error handling but is otherwise complete for its complexity.

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

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

Schema coverage is 100%, so both parameters are fully described in the input schema. The description does not add additional meaning beyond the schema, justifying the baseline score of 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 function: 'Generate a production-ready llms.txt file for any URL so AI crawlers can index the site cleanly.' It specifies the output format and distinguishes itself from sibling tools, none of which perform a similar task.

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

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

The description provides explicit use cases: 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not mention when not to use it or compare directly with 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns specific fields and supports an optional include_inactive parameter, which complements the annotations 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?

Two sentences with no redundancy. The first sentence lists the purpose and return fields, the second provides usage context. Every word 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?

Despite no output schema, the description enumerates return fields. It covers the parameter and usage context. Annotations provide safety cues. The tool is fully described for its 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?

The description adds meaning beyond the schema by stating the default behavior ('active subscriptions') and the effect of the include_inactive parameter. Since schema coverage is 100% and the description clarifies defaults, it scores high.

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 ('List the caller's active subscriptions') and the specific fields returned. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing, and provides context for usage.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This gives practical usage guidance, though it could also state 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool is keyless and rate-limited to ~1 request/second, which provides behavioral context beyond 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 sentences, zero waste. First sentence defines purpose and input format; second sentence adds usage guidance. Front-loaded with the most critical 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?

With one parameter, full schema coverage, and comprehensive annotations, the description covers the essential use case. It could mention the expected output format (e.g., manufacturer name or 'Unknown'), but the lack is minor 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%, so the baseline is 3. The description repeats the schema's guidance on acceptable MAC formats (full MAC or first 6 hex digits) and adds keyless/rate-limit info, but does not significantly enhance parameter 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 performs a MAC address to hardware manufacturer lookup using macvendors.com, with a specific verb ('lookup') and resource. It distinguishes itself from sibling tools by focusing on MAC OUI resolution, 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?

The description mentions keyless access and a rate limit (~1 req/sec), providing usage context. It does not explicitly state when not to use the tool or suggest alternatives, but the sibling tools are unrelated, so no confusion arises. A brief note on avoiding overuse would enhance this.

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

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

Discloses that feedback is sent to the Pipeworx team, read daily, rate-limited to 5 per identifier per day, and free. Annotations are all false, so no contradiction; description 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 a single paragraph but well-structured and covers all necessary points without redundancy. Slightly dense 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?

For a feedback tool with no output schema, the description fully covers purpose, usage, parameters, and behavior. No missing information given the tool's 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%, but description adds context for the enum values (e.g., 'bug = something broke or returned wrong data') and explains the context object's purpose, going beyond 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 is for providing feedback to the Pipeworx team about bugs, missing features, or praise. It distinguishes itself from sibling tools which focus on queries or data retrieval.

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: for bugs, feature/data_gap requests, or praise. Provides instructions on what to describe (tool/packs) and what to avoid (end-user prompts). Includes rate limit and cost information.

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, openWorldHint, and destructiveHint. The description adds valuable context: it's derived from an analytics engine, contains no PII, and is cached with 5min-1h refresh. This goes beyond the annotations and informs the agent about data freshness and privacy.

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 a clear structure: a lead sentence, followed by bullet-point use cases, and notes on derivation and caching. Every sentence adds value, though it could be slightly more compact 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?

Despite lacking an output schema, the description explains what is returned (tools, packs, counts) and notes caching and derivation. It covers the tool's behavior sufficiently for a simple, read-only tool with one parameter.

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

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

The single parameter 'window' is fully described in the schema (100% coverage). The description reinforces the meaning by explaining trade-offs between shorter and longer windows. This adds extra context that helps the agent choose appropriately.

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 returns 'top tools, top packs, and total call volume' for a given window, using specific verbs and resources. It distinguishes from sibling tools like 'ask_pipeworx' by focusing on trending signals from other agents, making the purpose unambiguous.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choices, aligning with common agent needs) and explains window trade-offs. However, it does not specify when to avoid using this tool or mention alternatives, keeping it from a perfect 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?

The description discloses algorithmic details (monotonicity violations, partition-sum checks, Jaccard similarity threshold, partition filter) and failure case beyond the annotations (readOnlyHint, idempotentHint). 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, but slightly verbose. Every sentence adds meaning, and key information is front-loaded.

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

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

Given no output schema, the description explains the response structure (opportunities, partition_check). It covers error conditions, algorithmic nuances, and usage context comprehensively.

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 coverage, the description adds significant value by explaining the modes, recommended inputs, and algorithmic context beyond the schema's field 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 it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes two modes (event and topic). While it doesn't explicitly contrast with sibling tools, the verb and resource are specific and scoped.

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 requires one of 'event' or 'topic', warns that no args fails, and recommends when to use each mode. It provides clear context for usage but does not enumerate exclusions or 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 comprehensively discloses behavioral traits beyond annotations: it details the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and their calculations, explains edge_pp_net after slippage, 24h-move warning, caching ('Cached 1h at the KV level'), and diagnostics. This adds significant value 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 very detailed and front-loaded with purpose and segments, but it is quite lengthy with many specific formulas and examples. While comprehensive for a complex tool, it could be slightly more concise without losing critical information. The structure is logical and easy to follow.

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 is exceptionally complete. It covers the response structure (by_segment, fed_candidates, _diagnostics), edge cases (Fed bets excluded), and diagnostics for empty segments. All aspects needed for proper invocation are addressed.

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

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

Schema coverage is 100% with all 9 parameters described. The tool description adds further context by grouping them as 'TRADEABLE-EDGE KNOBS' and explaining their role in filtering opportunities. This complements the schema and provides practical usage insights, exceeding the baseline 3 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('opportunities'), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on detecting mispricings for daily betting.

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

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

The description provides clear usage context ('Built for "what should I bet on today"') and explains the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) that control when to use. However, it does not explicitly state when not to use this tool or compare it directly to siblings like polymarket_arbitrage, which would improve 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 extensively discloses behavioral traits: read-only nature (consistent with annotations), response structure including safety fields (compatibility_warning, temporal_alignment), and limitations. It goes far beyond annotations by explaining edge cases and interpretation 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 verbose but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the purpose and uses bullet-like formatting. Could be slightly trimmed but earns its length.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure, safety fields, temporal alignment, and error conditions. It covers complexity well and prepares the agent for realistic outcomes.

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. The description adds significant context: lists all 10 topic shortcuts, explains override behavior for explicit fields, and provides examples. This adds value beyond 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 identifies the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison specifically.

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

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

The description provides explicit usage guidance: two modes (topic shortcuts and explicit events), explains when spreads are valid vs invalid due to bet shape mismatches, and warns that most pre-mapped topics currently return compatibility warnings. It does not explicitly contrast with sibling tools but covers when/why to use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context about scoping and the optional key behavior. 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?

Three sentences, front-loaded with main action, then usage context and related tools. 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?

Covers main behaviors and scope. No output schema, but description adequately indicates return values (value or list of keys). Could mention return format, but sufficient for an agent.

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

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

Schema coverage is 100% with key description. Description adds value by explaining the effect of omitting the argument (list all keys), which is 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 retrieves a saved value by key or lists all keys if omitted. It distinguishes from siblings 'remember' and 'forget' and provides concrete examples.

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

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

Explicitly tells when to use (look up stored context) and implies when not to (save/delete via siblings). Also clarifies scoping to identifier.

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

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

The description discloses the mark_read parameter's side effect (flagging returned events as read), which contradicts the readOnlyHint=true annotation. This is an annotation contradiction, causing the score to drop to 1.

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

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

Concise paragraph with front-loaded purpose. Every sentence adds value, though some details like 'Polls work fine' could be integrated but do not harm 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?

Completeness is high: covers return fields (source, citation_uri, raw payload), parameter usage, polling behavior, and alternative access method. No output schema, but description compensates adequately.

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

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

Adds significant value beyond the schema: explains type with example ('sec_8k'), elaborates on mark_read and unread_only effects, and clarifies citation_uri format. Since schema coverage is 100%, baseline is 3 but the description elevates to 5.

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 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools by focusing on subscription alerts with unique features like mark_read and filters.

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

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

Provides context for polling and alternative access via GET endpoint, but lacks explicit guidance on when to use this tool versus sibling tools like recall or list_subscriptions.

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 (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: fan-out strategy, fallback mechanisms, date parsing, partial failure modes (USPTO soft-fail), and return structure. 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?

Single dense paragraph that is well-organized: purpose first, then sources, parameter details, return structure, and alternative tool. Every sentence adds value; no wasted words.

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

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

Despite no output schema, the description explains the return format (changes grouped by source, total_changes, citation URIs). Covers error/fallback behavior for news and patent sources. Complete for a query 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%, yet the description adds meaning: explains 'since' accepts ISO date or relative shorthand and suggests default '30d' for monitoring; clarifies 'value' can be ticker or CIK. Adds practical usage guidance.

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 specifies the tool provides a change feed for a company, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It uses verbs like 'change feed' and 'fans out', and distinguishes from sibling 'entity_profile' by contrasting dynamic vs static info.

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

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

Explicitly states when to use this tool (for 'what's new' type queries) and when to use the alternative ('entity_profile' for static profile). Also explains fallback logic (GDELT preferred, GNews when rate-limited) 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?

Description adds behavioral details beyond annotations: scoped by agent identifier, authenticated vs anonymous persistence (24h). Annotations indicate idempotentHint=true (matches save semantics) and 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?

Single paragraph, front-loaded with purpose. Every sentence adds value, no redundancy. Highly concise and 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 simple tool (2 params, no output schema), description covers purpose, usage, behavioral nuances (scoping, persistence duration), and references sibling tools for lifecycle. Complete for agent understanding.

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?

Input schema covers 100% of parameters with descriptions. Description adds little beyond schema for parameters (only mentions key-value pair scoping). Baseline 3 applies.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource. It distinguishes from sibling tools by explicitly mentioning pairing with 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 states when to use: 'Use when you discover something worth carrying forward'. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. Lacks explicit when-not guidance, 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?

Annotations confirm readOnly, openWorld, idempotent, non-destructive. Description adds that calls cascade through multiple endpoints internally, and details return format for each type (company: ticker, CIK, name, URI; drug: RxCUI, ingredient, brand, URI), providing value beyond annotations.

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

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

Description is structured with examples and supported types. While a single paragraph, it front-loads query patterns and maintains conciseness without redundancy, earning its place.

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

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

Despite no output schema, description fully explains return values for both entity types, internal process, and citation URIs. Complete enough for the agent to understand tool behavior and outputs.

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%, baseline 3. Description adds meaning by explaining accepted input formats (ticker, CIK, or name for company; brand or generic for drug) and mentions auto-disambiguation, enhancing 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?

Description clearly states it resolves user-spoken names to canonical identifiers, with examples like 'ticker for...' and 'CIK for...', and instructions to use first when needing an ID. Distinguishes from siblings by specifying its role as the initial lookup step.

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

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

Explicitly tells agent to use FIRST when a name is available but an ID is needed. Does not provide explicit when-not-to-use scenarios, but the context of identifier resolution is clear and substitutes for 2-3 manual 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?

The description adds significant behavioral detail beyond the provided annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains that the tool probes each entity using ai_visibility_check, returns a ranked list with score, confidence, and signal density, and treats the first entity as the subject. No contradiction with annotations.

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

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

The description is concise, with four sentences that front-load the core action and purpose. Every sentence adds value: main function, process, example use case, and return format. No redundancy or filler 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 (composite with 4 parameters, no output schema), the description thoroughly covers return format (ranked list with score, confidence, signal density), sub-tool usage (ai_visibility_check), parameter semantics (entities ordering, context disambiguation), and the overall workflow. It provides sufficient information for an agent to understand and 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%, but the description adds meaningful context beyond schema definitions. For example, it clarifies that the first entity in the 'entities' array is treated as the 'subject' for narrative, and provides usage examples for the 'context' parameter (e.g., 'B2B SaaS'). This enriches the agent's 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's purpose: comparing AI visibility across multiple entities side-by-side, with probing, ranking, and surfacing most/least recognized. It provides a concrete example ('does Claude know about us as well as our competitors?') and distinguishes the tool's specific competitive audit function 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 states when to use the tool ('useful for competitive AI-marketing audits') and gives a practical scenario. While it references the sub-tool ai_visibility_check, it does not explicitly exclude cases or compare directly to sibling tools like compare_entities, which would earn 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 indicate read-only, idempotent, non-destructive. The description adds valuable context: the composite call fans across two services, first measurement can take 5-30s, partial failures degrade gracefully with 'sources_failed' returned. No contradiction with annotations.

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

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

The description is well-structured: starts with a clear verb ('Composite...check'), explains when to use, lists return fields, then covers edge cases and limitations. Every sentence adds value, and it is front-loaded with the essential 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 complexity (composite call, multiple data sources, no output schema), the description fully explains what is returned, including edge cases (partial failure, first measurement delay, NPM-only scope). An agent can fully understand behavior and limitations without additional documentation.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaningful information beyond the schema: it mentions scoped packages and default version, which are already in the schema parameter descriptions. No additional syntax or constraints 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, covering license, advisories, version history, bundle size, dependency count, and ES module support. It distinguishes from siblings by specifying the composite nature and the two external sources (deps.dev and bundlephobia).

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides 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?

Annotations already declare readOnlyHint, idempotentHint; description adds internal details: embedding model, cosine similarity, overlapping windows, character cap and truncation flag. 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?

Single dense paragraph with no wasted sentences. Front-loaded with purpose, then usage, then technical detail. Every sentence earns its place.

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

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

Despite no output schema, description explains return values (passages with offsets and scores) and truncation behavior. Comprehensive for a 3-parameter search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that 'text' is the document body, 'query' is natural-language, 'limit' max passages, default 5, and char limit. This enriches understanding 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?

The description clearly states the tool performs semantic search inside a fetched record, specifying verb ('search'), resource ('record'), and distinguishing from siblings by mentioning pairing with ask_pipeworx_grounded.

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 ('when record is too big for prompt'), provides pairing guidance, and notes context. However, it lacks explicit when-not-to-use scenarios.

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

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

The description says 'Create a proactive monitoring subscription', which is a write operation, yet annotations include readOnlyHint: true, indicating the tool does not modify state. This is a direct contradiction, severely harming trustworthiness.

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, front-loading the core action, then providing examples and conditions in a readable paragraph. 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?

Despite no output schema, the description states it returns the new subscription ID, covers type-specific filters, delivery channels, and account requirements. It is complete for the tool's complexity.

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

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

Schema coverage is 100% and the description adds significant value: it explains the type parameter's only value, provides an example for params (e.g., ticker, items), and details delivery options including SMS and email with 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 creates a proactive monitoring subscription for live-data event streams, with a specific example (type sec_8k). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation of subscriptions.

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

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

The description provides context on when to use the tool (to monitor events) and prerequisites (Pipeworx OAuth account). It explains delivery channels but does not explicitly state when not to use it or compare with alternatives, which is slightly lacking.

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 states a mutation (deactivate row) but annotations include readOnlyHint=true, contradictory. This serious inconsistency undermines transparency. IdempotentHint=true also conflicts with mutation.

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 action, efficient and clear with no unnecessary text.

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 covering ownership and deactivation behavior, the annotation contradiction leaves the agent confused about read-only vs. mutation, reducing 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% with one parameter fully described; description adds no additional parameter info, earning baseline score.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource, distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions') and notes that the row is deactivated not deleted, implying when to use. Lacks explicit exclusions but provides good 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, openWorldHint, idempotentHint, and destructiveHint. Description adds rich behavioral detail: internal workflow (NL parsing → entity resolution → data lookup → numeric comparison), return format (verdict with types, structured form, actual value with citation, percent delta), and its efficiency benefit. 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?

Description is informative but somewhat lengthy. It front-loads the core purpose with example queries and logically structures the explanation of scope, output, and benefits. Every sentence adds value, but 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 tool complexity (claim verification over structured financial data), the description covers purpose, usage scope, internal workflow, output format, and efficiency gains over alternative approaches. No output schema exists, but the description sufficiently explains 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?

Only one parameter 'claim' with schema coverage 100%. Description adds contextual meaning beyond the schema by specifying claim examples and the supported domain (company-financial). Does not elaborate on syntax or formatting, but the examples are sufficient.

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

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

Description uses specific verbs (validate, fact check, verify) and clearly states the tool's purpose: natural-language claim verification. It distinguishes from siblings by noting it replaces 4-6 sequential calls and specifies the domain (company-financial claims via SEC EDGAR + XBRL).

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and defines the supported claim scope. Does not explicitly state when not to use, but the domain limitation is clear.

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