Spoonacular

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

Annotations already indicate readOnly, openWorld, non-destructive. The description adds behavioral details: routing to appropriate tool, filling arguments, returning structured answer 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 front-loaded with the key preference statement, then elaborates with categories and examples. While slightly verbose, all content is useful 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?

For a single-param natural language gateway tool, the description is comprehensive: covering what it does, when to use, types of questions, and output format (citations). No output schema needed; description covers expectations.

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 1 parameter 'question' with generic description. The description provides extensive guidance on what constitutes a good question, with categories and examples, adding 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 answers factual questions using structured data from 575 verified sources across 2,520 tools, with specific examples (SEC filings, FDA data, etc.) and explicitly prefers over web search. It distinguishes its purpose from generic search.

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 prefer over web search for factual queries and provides many examples of when to use. However, it does not explicitly say when not to use (e.g., creative tasks), though the context strongly implies 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 mark it as read-only and non-destructive. The description adds significant behavioral context: it resolves markets, classifies bets, fans out to relevant packs, and returns a comparison. No contradictions with annotations.

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

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

Description is front-loaded, concise, and covers purpose, inputs, process, output, and use cases in four sentences. Every sentence adds value, though it could be slightly tighter.

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?

Explains output (evidence packet + comparison) and process (resolution, classification, fan-out). Lacks details on output structure or formats, but sufficient for core demo product given no 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 covers both parameters with descriptions. The description adds value by clarifying that 'market' can be slug, URL, or question text (with examples) and that 'depth' defaults to 'thorough', which is not stated in the schema.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies the inputs (slug, URL, or question text) and output (evidence packet + comparison). However, it does not explicitly distinguish from siblings like ask_pipeworx or polymarket_edges, which handle related but different tasks.

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 ('should I bet on X?', 'what does the data say?'). Implicitly positions itself as superior to manual discovery, but does not mention when to use alternative tools or when not to use this one.

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 and destructiveHint=false, and the description adds detailed behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific financial fields (revenue, net income, cash, debt), and return format (paired data + 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?

Single paragraph with clear structure: purpose statement, usage triggers, type explanations, and efficiency claim. Every sentence contributes essential information without redundancy.

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

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

Despite lacking an output schema, the description sufficiently explains return data (paired data + citation URIs) and covers both entity types with specifics. For a comparison tool with two parameters and clear annotations, it is complete enough for an agent to invoke correctly.

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

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

Input schema has 100% description coverage for both parameters. Description adds value beyond schema by explaining what data each type pulls and how to format values (tickers vs. drug names). However, it does not detail individual parameter semantics 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 compares 2–5 companies or drugs side by side, with specific verb 'Compare' and resource 'entities'. It distinguishes from sibling tools like entity_profile (single entity lookup) by explicitly focusing on multi-item comparison.

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

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

Provides explicit trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger') and states it replaces 8–15 sequential agent calls, giving clear when-to-use guidance. Also explains two subtypes (company, drug) with specific 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=true and destructiveHint=false, but the description adds no behavioral context beyond 'Unit conversion.' It fails to disclose that conversion depends on ingredient density or that results may vary (openWorldHint=true). The agent gains little insight into tool behavior from the description.

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 extremely short (two words) but fails to convey necessary information. Conciseness should not sacrifice completeness; here, it is under-specified and does not add 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 four required parameters, no output schema, and no schema descriptions, the description is woefully incomplete. It omits any detail about when to use it, how to structure inputs, or what to expect as output.

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 0%, and the description provides no explanation for any of the four parameters. It doesn't clarify valid units, the role of ingredientName, or constraints like sourceAmount range. The agent must infer all meaning from parameter names 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 'Unit conversion' is vague and only slightly more informative than the tool name. It doesn't specify that the conversion is for ingredient amounts, which the input schema clearly implies. This lacks the specificity needed for an agent to distinguish it from general unit converters.

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 usage guidelines are provided. There is no mention of when to use this tool vs. sibling tools like ingredient_information or recipe_ingredients, nor any context about prerequisites 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds beyond that by stating it returns 'top-N most relevant tools with names + descriptions', which is useful behavioral context. No contradictions.

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

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

The description is concise, with three well-structured sentences. It front-loads the primary action, provides usage guidance, and lists example domains efficiently. Every sentence adds value without fluff.

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

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

Given the tool's simplicity and the presence of good annotations and schema, the description is mostly complete. It explains the tool's purpose, usage context, and return format. However, it could mention ordering criteria (relevance) or any limitations, but these gaps are minor.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description repeats the query parameter's purpose ('natural language description') but does not add additional semantic details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Find tools' and the resource 'tools by describing the data or task'. It distinguishes itself from sibling task-specific tools by being a meta-discovery tool, and lists example domains to clarify scope.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available', providing clear context. However, it does not explicitly state when not to use it or list alternative tools.

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

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

Discloses return contents (SEC filings, fundamentals, patents, news, LEI) and mentions citation URIs. Annotations already provide read-only and open-world hints; description adds specific behavioral details 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?

Six sentences covering purpose, usage triggers, and return items. Front-loaded main purpose; could be slightly more compact but is well-organized and free of fluff.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (SEC filings, fundamentals, patents, news, LEI) and the format of input identifiers. This is complete for an agent to invoke and interpret 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 coverage is 100% with clear parameter descriptions. The description essentially restates the schema's examples and notes, adding minimal new semantic value beyond what is already in the schema.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It identifies specific user queries that trigger use, and implicitly distinguishes from siblings like resolve_entity and compare_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?

Explicitly states when to use (user asks for company profile) and when not to use (if only have a name, use resolve_entity first). Also mentions alternative tool resolve_entity.

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

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

Annotations already set destructiveHint=true, and description confirms deletion. It adds context about why deletion is appropriate (stale, done, sensitive), which is valuable beyond annotations.

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

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

Two sentences with no wasted words. The key information is front-loaded: 'Delete a previously stored memory by key.' Followed by usage guidance. Perfectly concise.

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

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

For a simple delete operation with one parameter and no output schema, the description covers purpose, usage, and pairing with siblings. It could mention behavior for non-existent keys, but overall is 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?

Schema coverage is 100% with a clear description of the 'key' parameter. The description does not add additional parameter semantics, so baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb, resource, and method. It distinguishes from siblings by mentioning 'Pair with 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, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall, providing clear 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds no behavioral context beyond these, missing opportunity to explain return format or side effects.

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?

While short, the description is under-specified and lacks essential information. Conciseness should not sacrifice completeness.

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, three parameters with zero description, and no usage guidance, the description is severely incomplete and fails to enable correct tool 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?

With 0% schema description coverage, the description does not compensate. It fails to explain what 'id', 'unit', or 'amount' mean or how they are used in the tool.

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 'Ingredient detail.' is a tautology that restates the tool name without a specific verb or resource. It fails to distinguish this tool from siblings like 'ingredient_search' or 'recipe_ingredients'.

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 is provided on when to use this tool versus alternatives. The description lacks context on appropriate scenarios 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 indicate readOnlyHint, openWorldHint, and destructiveHint. The description adds no additional behavioral context (e.g., what data is returned, pagination, or API 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?

Overly terse; sacrifices informativeness for brevity. A single sentence without structured details wastes an opportunity to convey essential functionality.

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 four undocumented parameters and no output schema, the description is severely incomplete. It does not explain return values, filtering behavior, or how the tool integrates with 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 parameter coverage is 0%, and the description provides no information about the parameters (query, sort, number, intolerances). The description fails entirely to compensate for missing 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?

Description 'Ingredient search' is a tautology that restates the tool name. It does not clarify the specific scope or differentiate from sibling tools like ingredient_information or recipe_search.

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 versus alternatives such as ingredient_information or recipe_search. Missing context on typical use cases 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 include 'readOnlyHint: true' but the description implies generation (potential write). The description adds no behavioral context beyond annotations, leaving ambiguity about side effects or prerequisites.

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 phrase that is under-specified, lacking necessary detail. While brief, it sacrifices clarity for conciseness.

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

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

With no output schema, no parameter descriptions, and a three-word description, the tool definition is severely incomplete for an agent to use correctly.

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

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

Four parameters exist with 0% schema documentation. The description provides no information about what parameters mean, expected formats, or examples, failing to compensate for the lack of 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 'Generated meal plan' is vague and reads as a noun phrase rather than an action. It does not specify what the tool does (e.g., create, retrieve, or compute) and fails to distinguish it from similar sibling tools like 'meal_plan_week'.

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 is provided on when to use this tool versus alternatives. Sibling tools like 'meal_plan_week' likely overlap in functionality, but no comparison or context is given.

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 and openWorldHint=true, so safety and non-determinism are disclosed. However, the description adds no behavioral context beyond these annotations. The agent does not learn what 'plan' means operationally, e.g., whether it returns recipes or just a schedule.

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 overly terse (three words). While concise, it fails to provide essential information. Every sentence should earn its place, but here it is merely a restatement of the tool's name.

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

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

Given the lack of output schema, three undocumented parameters, and no usage guidance, the description is completely inadequate. The agent has insufficient information to invoke the tool correctly.

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

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

Schema description coverage is 0%, but the description does not explain any of the three parameters (diet, exclude, targetCalories). The agent cannot infer valid values or their purpose, making the tool nearly unusable.

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 '7-day plan' is extremely vague. It does not specify the action (e.g., 'generate', 'retrieve') or the resource clearly. The name implies a weekly meal plan, but the description adds little clarity and does not distinguish from the sibling tool 'meal_plan_generate'.

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 is provided on when to use this tool versus alternatives like 'meal_plan_generate'. There is no context on prerequisites, filters, or use cases. The agent receives no help in selecting the appropriate tool.

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

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

Discloses that the tool is free and does not count against tool-call quota. Also reveals rate limiting. Annotations do not contradict; destructiveHint is false consistent with non-mutating feedback submission.

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 single paragraph of 5 sentences, front-loaded with purpose. Every sentence adds value: usage examples, constraints, and quota info. 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 feedback tool with 3 parameters (one nested), the description covers all aspects: purpose, when to use, how to structure feedback, rate limits, and quota impact. No output schema needed; behavior is self-explanatory.

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, but description adds contextual meaning to the 'type' enum (e.g., 'bug = something broke or returned wrong data') and explains the 'message' field's purpose (be specific, 1-2 sentences). Provides examples that enhance 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 the tool is for giving feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes from sibling tools like ask_pipeworx by being exclusively for reporting issues or suggestions.

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 specifies when to use the tool: for bugs, feature requests, data gaps, or praise. Provides constraints: describe in terms of Pipeworx tools/packs, don't paste end-user prompts. Also mentions rate limit of 5 per identifier per day.

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 substantial behavior beyond annotations: explains internal logic (walking child markets, grouping across events, checking monotonicity). Annotations are consistent with read-only, open-world nature, and description confirms no destructive effects.

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

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

Well-structured with clear sections for each mode. Every sentence provides value; no redundant or vague statements. Front-loaded with purpose.

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

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

Despite no output schema, the description specifies what the tool returns (ranked opportunities with reasoning). Covers both modes comprehensively, including edge cases (e.g., Polymarket separating events by cutoff dates). 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?

Both parameters are fully described with schema coverage at 100%. The description explains how each parameter triggers a different mode and provides examples, adding meaningful context 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 the tool finds arbitrage opportunities via monotonicity violations, with two explicit modes (event and topic) and distinct behaviors for each. It differentiates from siblings like polymarket_edges by specifying its unique cross-event grouping logic.

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

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

Provides explicit guidance for when to use each mode, including examples and reasoning for cross-event mode. Explains limitations of single-event mode and why topic mode is needed for related markets across events.

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, and destructiveHint. The description adds rich behavioral context: it uses a lognormal model from FRED + live coinpaprika price, groups by asset, computes model probability, and ranks by absolute edge. 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 a single, well-structured paragraph of 4 sentences. It front-loads the core purpose, then explains the model and process, then the output. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains what is returned (top N ranked by edge magnitude with suggested trade direction). It also covers data sources (FRED, coinpaprika), the model, and the ranking process. The tool has low complexity and is completely specified for its purpose.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds little beyond restating the purpose of the limit parameter (returns top N). It does not provide new semantic detail about how window or min_edge_pp affect behavior 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 scans high-volume Polymarket markets and returns those with largest disagreement between Pipeworx data and market price. It uses a specific verb ('scan', 'return') and resource ('Polymarket markets'), and distinguishes itself from siblings by focusing on edge discovery for betting opportunities, not arbitrage.

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

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

The description explicitly frames the tool for the 'what should I bet on today' question, indicating when to use it. It mentions avoiding manual paging, but does not explicitly state when not to use it or compare to siblings like 'polymarket_arbitrage'. The context is clear enough for an agent.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, covering safety. The description adds no further behavioral context, such as what data or operations are involved, but 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?

The description is extremely brief (two words), which is under-specification rather than effective conciseness. It fails to provide necessary details.

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

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

With no output schema and a sparse description, the tool definition provides almost no context about what the tool returns or how to use it. Sibling tools exist but are not differentiated.

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 0% description coverage, and the tool description does not explain the 'id' parameter's meaning, format, or constraints. This leaves the agent without guidance on parameter usage.

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 'Product detail' is vague and does not specify an action verb or the resource being acted upon. It fails to distinguish from sibling tools like product_search or recipe_information.

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 is provided on when to use this tool versus alternatives. There is no mention of scenarios or exclusions, leaving the agent without context 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?

The description adds no behavioral traits beyond what annotations already provide. Annotations indicate readOnlyHint=true and destructiveHint=false, so agents know it is safe to use, but the description should disclose additional behavior like result set limitations or filtering characteristics.

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 extremely short, but it sacrifices clarity for brevity. It fails to convey necessary information and is more under-specified than concise.

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

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

Given the tool has 5 parameters and no output schema, the description should provide sufficient detail about parameters, usage, and return format. It is completely inadequate for an agent to use 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 description coverage is 0%, and the description mentions no parameters. The description does not explain what 'query', 'number', 'offset', 'minCalories', or 'maxCalories' mean or how they affect the search.

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 'Branded product search.' indicates this tool searches for products, specifically branded ones. It uses a clear verb ('search') and resource ('product'), but the term 'branded' is ambiguous and not necessary. It lacks specificity compared to sibling tools like product_information or recipe_search.

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 is provided on when to use this tool versus alternatives such as product_information or recipe_search. The description offers no context for 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?

Adds scoping details (anonymous IP, etc.) beyond annotations, and explains behavior with optional key. Annotations already indicate readOnlyHint=true, so no contradiction.

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

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

Three sentences, efficiently structured with purpose first, then usage context and pairing. 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?

Coverage is complete given the tool's simplicity: explains both invocation forms, scoping, and relationship to siblings. No output schema needed.

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

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

Schema covers parameter fully with description; description adds the behavior of omitting key to list all keys, which is additional 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?

Description clearly states the tool retrieves values saved via 'remember' or lists all keys when 'key' is omitted, effectively distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

Explicitly states when to use (look up stored context to avoid re-deriving) and mentions pairing with 'remember' and 'forget', though does not explicitly state when not 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?

The description adds value beyond annotations by explaining the fan-out to multiple sources (SEC, GDELT, USPTO) and the return format, though it does not cover all potential behaviors.

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

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

The description is well-structured and front-loaded with purpose, but slightly dense; it could be more concise without losing 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 and lack of output schema, the description adequately covers parameter usage and return structure, though it omits error handling or pagination details.

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 meaningful examples and typical values for 'since' and 'value', 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?

The description clearly states the tool's function: 'What's new with a company in the last N days/months?' and provides specific query examples, distinguishing it from sibling tools like entity_profile.

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 when to use the tool with example queries, but does not mention when not to use it or alternative tools, leaving some gap.

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 and destructiveHint=false, so the description's 'Recipe detail.' is consistent but adds no behavioral context. The minimal description 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?

The description is only two words, which is under-specified rather than concise. It omits essential information needed for correct tool invocation.

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 and the presence of multiple sibling tools with overlapping functionality, the description is completely inadequate. It does not clarify what the tool returns or how it differs from similar 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?

The description provides no explanation for the two parameters (id, includeNutrition). Schema description coverage is 0%, so the agent must guess at their meaning. This is a critical gap.

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

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

The description 'Recipe detail.' is vague and does not clearly specify what information is provided. It fails to distinguish from sibling tools like recipe_summary or recipe_nutrition, which also deal with recipe details.

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 versus alternatives. The description lacks any context about prerequisites, scope, or scenarios where this tool is appropriate compared to others.

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

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

The annotations (readOnlyHint=true, destructiveHint=false) already indicate a safe read. The description adds no behavioral context beyond that, such as what data is returned, any limitations, or required permissions. It does not contradict annotations (annotation_contradiction=false), but it contributes no additional transparency.

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

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

The description is extremely short (two words) but at the expense of clarity. It is not front-loaded with useful information. Every word should earn its place, but here the words 'Ingredient list' fail to provide meaningful guidance.

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 one parameter, no output schema, and 0% schema coverage, the description is grossly incomplete. It does not specify what ingredient list is returned (e.g., list of ingredients for a given recipe), the format, or any other necessary context. The agent cannot determine how to use this tool correctly.

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

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

The input schema has one parameter 'id' with 0% description coverage, meaning the description does not explain what 'id' represents (e.g., recipe ID, ingredient ID). The description provides no parameter-level information, so it adds no semantic value beyond the schema.

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

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

The description 'Ingredient list' is a noun phrase, not a verb+resource. It does not clearly state what the tool does; it merely restates the name in a slightly different form. The purpose is vague and leaves the agent guessing whether the tool retrieves an ingredient list for a recipe or something else.

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 when-to-use, when-not-to-use, or alternative tool guidance is provided. Given many sibling tools (recipe_information, recipe_nutrition, ingredient_search, etc.), the agent has no context to choose this tool over others.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds no behavioral insight beyond the annotations, such as what data is returned or any 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 extremely short (two words) but lacks structure, front-loading, or completeness. It is under-specified rather than efficiently conveying necessary 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 no output schema, no parameter explanations, and many sibling tools, the description is grossly incomplete. It does not indicate what nutrition fields are included (e.g., calories, macros) or how the tool fits into the recipe tool portfolio.

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 0%, and the description does not explain the single parameter 'id' (e.g., that it is a recipe ID). No value added over 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 'Nutrition breakdown.' indicates the tool provides nutrition information, but it lacks a verb and does not specify the resource (e.g., for a recipe by ID). It is somewhat clear but fails to differentiate from siblings like 'recipe_summary' or 'recipe_information'.

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 versus alternatives. There are many related sibling tools (e.g., recipe_information, recipe_summary), but the description provides no context for choosing this one.

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, destructiveHint=false, and openWorldHint=true. The description adds no behavioral context beyond these annotations, missing opportunities to clarify that cost breakdown may vary or depend on external factors.

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?

At only two words, the description is under-specified rather than concise. It lacks essential information for an agent to understand the tool's functionality.

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

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

Despite having annotations, the description is too sparse. For a cost breakdown tool, it should indicate what the output contains (e.g., total cost, cost per ingredient). Without this, the agent cannot effectively use the tool.

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

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

The input schema has one parameter 'id' with type number and no description. The description 'Cost breakdown' does not explain that 'id' likely refers to a recipe ID or what format it expects. Schema coverage is 0%, and the description adds no semantic value.

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 'Cost breakdown' is vague and fails to specify a verb or resource. It does not differentiate from sibling tools like recipe_information or recipe_ingredients. A clear purpose would be 'Get cost breakdown for a recipe'.

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 is provided on when to use this tool versus alternatives such as recipe_information or recipe_ingredients. The description lacks context for appropriate usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation with non-deterministic results. The description adds no behavioral details beyond the obvious meaning of 'random,' such as how randomness is achieved or if results are influenced by parameters.

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 only two words, which is under-specified rather than concise. It fails to provide necessary context while being excessively brief.

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 (2 optional parameters, no output schema), the description could be brief but still lacks essential details about parameter effects and return behavior. Annotations provide some safety context, but overall completeness is low.

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 does not explain the parameters 'tags' and 'number.' With 0% schema description coverage, the agent must infer meanings from names alone, which is insufficient for proper invocation.

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 'Random recipes' indicates the tool returns random recipes, but it lacks specificity about the scope (e.g., all recipes or a subset). It does not distinguish from siblings like recipe_search or recipe_similar, which have overlapping purposes.

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 versus alternatives such as recipe_search (for filtered queries) or recipe_similar (for finding similar recipes). The description provides no context for 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 provide readOnlyHint, openWorldHint. Description adds no new behavioral info like accepted parameter patterns, response format, or search behavior. With annotations present, description fails to add meaningful 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?

Extremely concise (2 words) but at the cost of clarity. Every sentence should earn its place; this description is under-specified and not useful.

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 and a complex context (many sibling tools), the description provides no guidance on usage, parameters, or results. Completely inadequate for an effective tool selection.

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 has no defined properties (100% coverage by default), but the open schema implies arbitrary parameters. Description does not explain what keys (e.g., query, cuisine) are expected, leaving the agent guessing.

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 'Complex recipe search' is vague; lacks specific verb and resource. It does not distinguish from sibling tools like 'recipe_information' or 'recipe_random'. Barely above a tautology.

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 versus alternatives. With many sibling recipe tools, no context on what makes this search 'complex' or what scenarios it suits.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. However, it adds no further behavioral context, such as that the tool returns a list of similar recipe IDs or items, or any potential limitations (e.g., dependency on a predefined similarity algorithm).

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?

At only two words, the description is terse but not effectively concise. It lacks a proper sentence structure and fails to convey essential information. Conciseness should not sacrifice clarity; here it does.

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

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

Given the absence of an output schema, the description should hint at the return format (e.g., list of recipe objects or IDs). It does not. The description is incomplete for a tool with two parameters and no output schema, leaving the agent without critical context about how to use it or interpret 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?

The input schema has two parameters (id and number) with 0% description coverage. The description 'Similar recipes.' does not explain what these parameters mean or how they influence the results. For example, it is unclear what 'number' refers to (e.g., count of results). The description adds no 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 'Similar recipes.' indicates the verb (find similar) and resource (recipes), but it is extremely vague and fails to distinguish from sibling tools like recipe_search or recipe_information. It lacks specificity about what similarity means or how it is determined.

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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or when not to use it. The description offers no context for decision-making.

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 and destructiveHint=false, but the description adds no behavioral context beyond the annotations. It does not explain what kind of summary is returned (e.g., text, key points) or any other traits like response format or performance characteristics.

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 two-word description is extremely brief but lacks substance, resulting in under-specification rather than effective conciseness. Every sentence should add value; here, the single sentence does not adequately describe the tool's functionality.

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 low complexity (single parameter, no output schema, clear annotations), the description is completely inadequate. It omits the return type, the content of the summary, and how the ID is used, leaving the agent unable to correctly invoke the tool without external knowledge.

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 0% schema description coverage and no explanation of the required 'id' parameter in the description, the meaning of the parameter is entirely dependent on context. The description fails to clarify that 'id' is a recipe identifier, offering no added 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 is 'Short summary,' which effectively restates the tool name 'recipe_summary' without clarifying what the summary pertains to. It fails to specify that it provides a summary of a recipe given its ID, making it vague and indistinguishable from siblings like 'recipe_information' or 'recipe_nutrition'.

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 is provided on when to use this tool versus alternative recipe tools such as 'recipe_information' or 'recipe_ingredients'. The description does not mention any conditional usage 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 indicate readOnlyHint=true, but the description adds no behavioral details (e.g., what 'taste' entails, output format, or side effects). The description provides minimal additional transparency.

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

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

The description is only two words, which is under-specified rather than concise. It lacks structure and fails to convey essential information.

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

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

Despite having only 2 parameters and no output schema, the description is grossly incomplete. It does not clarify what the tool returns, how 'normalize' affects output, or any context needed 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?

With 0% schema description coverage and no mention of parameters in the description, the tool provides no semantic clarity for the 'id' and 'normalize' parameters. The description fails to compensate for the schema gap.

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

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

The description 'Taste widget' is vague; it does not specify a verb or resource clearly. It fails to differentiate from siblings like recipe_information or recipe_nutrition, leaving the tool's exact purpose ambiguous.

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?

There is no guidance on when to use this tool versus alternatives. Sibling tools include many recipe-related functions, but no context for selection is provided.

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 it is a write operation (no readOnlyHint), persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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?

Concise and well-structured: first sentence defines purpose, second provides guidance, third gives examples, fourth explains storage, fifth persistence, sixth links to siblings. 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 write tool with no output schema, the description covers all necessary aspects: usage, parameters, persistence, and related tools. Completely 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?

Schema already describes key and value with examples. Description adds value by explaining the scope and usage context, but schema coverage is 100% so baseline is 3; the extra context justifies a 4.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, provides concrete examples (resolved ticker, target address, etc.), and distinguishes from siblings like recall and forget.

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

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

Explicitly says when to use it (discovering something worth carrying forward) and mentions pairing with recall and forget. Also explains scoping by identifier and persistence details.

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, openWorldHint), the description adds that the tool returns IDs plus pipeworx:// 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 paragraph with examples and clear structure. It is informative and not overly verbose, though slightly longer than minimal but justified by content.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what the tool does, when to use it, and what it returns (including example outputs). No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context with examples (e.g., 'Apple' → AAPL/CIK) and explains the purpose of the outputs, 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?

The description uses specific verbs ('look up', 'returns') and clearly states the resource (canonical/official identifiers for companies or drugs). It distinguishes from sibling tools by mentioning it replaces multiple lookup calls and should be used before other tools.

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

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

Explicitly states when to use: when a user mentions a name and an identifier is needed, and before other tools requiring official identifiers. Implies alternatives by stating it replaces 2-3 lookup calls, but does not explicitly list when not 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 and non-destructive behavior. The description adds meaningful context: returns a verdict with multiple possible values, structured form, actual value with citation, and percent delta. It also notes the tool replaces four to six sequential calls, providing insight into efficiency. 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 succinct with five sentences, front-loading the purpose. Every sentence adds value: purpose, usage trigger, scope, return values, and efficiency note. No unnecessary words or redundancy.

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

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

Given no output schema, the description thoroughly explains the return format (verdict types, actual value with citation, percent delta). It also covers the tool's scope and efficiency. For a single-parameter tool, this is complete and leaves no ambiguity about what it returns.

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

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

Schema description coverage is 100% for the single parameter 'claim'. The description adds example claim formats, but the schema already describes it as a natural-language factual claim. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds minimal extra semantics.

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

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

The description clearly states the tool's purpose: fact-check a natural-language claim against authoritative sources. It provides concrete examples and specifies the scope (company-financial claims). It is easily distinguishable from sibling tools, none of which perform fact-checking.

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

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

The description explicitly tells when to use the tool, citing trigger phrases like 'Is it true that…?'. It does not include explicit when-not-to-use instructions, but the context is clear. No alternative tools are mentioned, but among siblings, none are similar, so the guidance is adequate.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false. The description adds no behavioral context (e.g., what the pairing entails, data sources, or limitations). Minimal 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?

Extremely concise but at the expense of clarity. The single sentence is under-specified, failing to provide actionable 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?

No output schema, and description omits crucial details like return format, expected input format, and behavioral outcomes. Inadequate for a tool with 2 parameters.

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

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

Schema description coverage is 0%, so description must explain parameters. It does not: 'food' is undefined (type of food? format?), and 'maxPrice' lacks unit/currency context.

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 'Wine pairing.' is a tautology, restating the tool name without a specific verb or resource. It does not distinguish from sibling tools like wine_recommendation, leaving its purpose ambiguous.

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 versus alternatives. The description provides no context about scenarios, prerequisites, or when to avoid 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=true and destructiveHint=false, so the safety profile is known. However, the description does not add any behavioral context beyond the name. It omits details like whether it filters by available inventory, requires external data, or returns recommendations in a specific format.

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 extremely short (4 words), which might be seen as concise, but it underspecifies the tool's purpose and behavior. It lacks the necessary detail to be useful, so it is not appropriately concise.

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

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

Given 4 parameters, no parameter descriptions, and no output schema, the description is severely incomplete. It does not cover what the tool returns, how parameters interact, or any constraints. This is inadequate for reliable agent 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 description coverage is 0%, so the description must explain parameter semantics. It provides no information about the 'wine' (string), 'price' (string), 'number' (number), or 'minRating' (number) parameters, leaving the agent without any usage hints.

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 is 'Wine recommendation.' which is a tautology of the tool name. It lacks specificity: it does not indicate what action is performed (e.g., suggest, find, provide) or the resource scope (e.g., by type, region).

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 usage guidance is provided. There is no indication of when to use this tool over sibling tools like 'wine_pairing' or 'ingredient_search', nor any context or prerequisites.

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