Wmata

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

Adds significant context beyond annotations: default model, cost structure (free vs BYO key), and return format per model (score, confidence, signals, raw_response). Annotations already indicate read-only, idempotent, non-destructive; description confirms and enriches with behavioral details.

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

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

Five sentences, front-loaded with action and key output. Every sentence adds info: probing action, scoring range, default model, key requirement, return structure, use cases. No waste.

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

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

Despite no output schema, description fully covers return values (per-model objects + combined view) and behavior (default model, key needed for Anthropic). With 4 parameters all described in schema, and clear use cases, it is complete for an agent to decide and invoke.

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 default usage for 'models' (omit for just workers-ai), when '_apiKey' is needed, and how 'context' helps disambiguate. This goes beyond the schema descriptions.

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

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

Clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100). The verb 'probe' and resource 'LLMs' are specific. However, it doesn't explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', though the focus on visibility scoring per model provides implicit distinction.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It implies when to use but does not specify when not to use or name alternatives. The context signals and sibling tools suggest alternatives exist, but the description doesn't address them.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns structured answers with pipeworx:// citation URIs and routes to a vast set of tools, which provides useful behavioral context 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 fairly long but well-structured with a clear hierarchy: preference, scope, examples, and fallback instructions. Each sentence adds value, though some redundancy could be trimmed. It's front-loaded with the most important instruction.

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 (routing to 4,774 tools), the description thoroughly covers its purpose, usage boundaries, examples, and return format (citations). No output schema exists, but the description explains what to expect, making it complete 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?

Schema coverage is 100% (all six parameters are aliases for 'question'). The description confirms natural language input and mentions aliases, but adds little beyond the schema. Baseline 3 is appropriate since the schema is already informative.

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

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

The description clearly identifies the tool as a query router to 4,774 tools for structured data, distinguishing it from web search and sibling tools like ask_pipeworx_grounded and deep_research. It specifies the verb 'routes' and the resource 'questions' with 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?

The description explicitly states 'PREFER OVER WEB SEARCH' and provides clear guidance on when to use (factual questions) and when to step up to alternatives (ask_pipeworx_grounded, deep_research). It lists query types and examples, making it easy for an agent to decide.

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

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

Description adds significant detail beyond annotations: extra LLM call, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and evidence extraction. 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?

Well-structured with key purpose front-loaded. Some verbosity but every sentence adds value. Slightly long but justifiable given 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 return format, refusal reasons, use cases, and cost trade-off. Lacks explicit mention of routing across many sources but references sibling behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning to parameters 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, extracts answers using only tool results, and distinguishes from ask_pipeworx by being grounded and refusal-prone.

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 (answers to be quoted/cited/acted on, must not invent facts) and when to prefer ask_pipeworx (casual lookups, cheaper).

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, idempotentHint, destructiveHint, and the description extensively adds behavioral traits: fan-out to data packs, response shapes, resolver contract with confidence levels, parent event extractor, news fallback, safety short-circuiting, wide-spread handling, and resolution-rule risk. No contradictions with annotations.

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

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

The description is lengthy but front-loaded with main purpose and usage. Every sentence adds value, but could be more concise. Structure is logical with sections for classifiers, examples, response shapes, etc.

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

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

Given complexity (3 params, no output schema), the description is extremely complete: covers inputs, outputs, edge cases (closed markets, low confidence), safety, resolution risks, and includes specific examples. Compensates well for lack of output schema.

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

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

Schema coverage is 100%, and description adds significant meaning: explains market input accepts different formats, depth enum options with context (quick vs thorough) and default, include_raw with size implications. Fan-out examples provide concrete 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 researches a Polymarket bet by pulling Pipeworx data, with specific verb 'Research' and resource 'bet'. It lists input types and output evidence packet. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though usage hints are given.

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

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

Explicit usage scenarios are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It gives classifiers and fan-out examples. No explicit 'when not to use' or alternatives, 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 already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description aligns with these and adds return field details, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Single sentence that is front-loaded with the action and resource. No wasted words; every phrase 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?

Output schema exists, so return value explanation is not necessary. The description mentions return fields, adding context. However, it lacks guidance on the time scope of 'current' or rate limits. Still adequate for a simple fetch 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?

With zero parameters and 100% schema coverage, the description does not need to explain parameters. Baseline 4 is appropriate as the description adds no parameter info but is not required to.

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 fetches current WMATA bus service alerts and incidents, specifies the return fields, and distinguishes from siblings like rail_incidents and bus_routes.

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 like rail_incidents or bus_predictions. The description does not provide explicit when/when-not or context for 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it is real-time and lists return fields, but does not disclose additional behavioral traits like rate limits or authentication needs. 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, sentence with clear action and output. It is front-loaded and contains no unnecessary words. Every sentence earns its place.

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

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

The tool is simple (1 param, no nested objects, has output schema). Description covers purpose and output fields adequately. Missing any note on error handling or edge cases, but overall complete for most use 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 coverage is 0% (no descriptions in schema). The description mentions stop_id is required but does not explain its format, valid values, or how to obtain it. With zero coverage, the description should compensate but only minimally adds 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 clearly states it fetches real-time next-bus arrival predictions for a WMATA bus stop by stop_id, and lists specific return fields (route ID, direction text, vehicle ID, minutes until arrival). This is specific and distinguishes from sibling tools like bus_incidents or bus_route_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?

The description implies usage for retrieving bus arrival predictions but does not explicitly state when to use it versus alternatives or mention when-not-to-use. No exclusions or alternative tool names are 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by specifying the exact output (direction names, stops, coordinates). No contradictions. Additional context about date behavior would improve 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?

Single informative sentence, front-loaded with verb 'Fetch'. No wasted words. Concisely captures core functionality and output.

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

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

Given output schema exists, description adequately covers purpose and outputs. May lack details on date format or route_id validation. For a 2-param tool, it's mostly complete but could add minor format hints.

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% (no property descriptions). Description mentions route_id and optional date but does not explain valid formats or constraints. Examples in schema help but description could add more guidance. Baseline 3 due to low coverage, but description only partially compensates.

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 fetches stop sequence and path details for a WMATA bus route by route_id and optional date, specifying return fields (direction names, stop names/IDs, geo coordinates). This distinguishes it from sibling tools like bus_routes (list all routes) or bus_stops (stop 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?

The purpose is clear but lacks explicit when-to-use vs alternatives. It implies detail-level usage for route shapes, but no exclusion or comparison with siblings like bus_predictions or bus_incidents. Good context, but no guidance on 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 declare safety traits (readOnly, idempotent, etc.), and the description adds behavioral context: it returns all WMATA bus routes with specific fields, without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core action and result, and concise without any filler. 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 tool with no parameters and a clear output schema, the description fully covers the purpose, return fields, and usage context, leaving no gaps.

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

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

There are no parameters, and the description appropriately omits parameter details. Per guidelines, baseline 4 for 0 params, and the schema coverage is 100%.

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

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

The description explicitly states 'Return all WMATA bus routes' and enumerates the fields returned (route ID, route name, line description), clearly defining the tool's purpose and differentiating it from sibling tools like bus_route_details and bus_predictions.

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

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

The description advises 'Use to enumerate available routes before fetching details or predictions,' providing context on when to use this tool and implying alternatives (details/predictions tools) for subsequent steps.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and behavior. Description adds no extra behavioral context beyond what annotations provide, such as authorization or rate limits.

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

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

Single sentence, front-loaded with purpose, parameter explanation, and return information. No unnecessary words, perfect length for the information conveyed.

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

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

Given output schema exists, description covers necessary aspects: what the tool does, parameters, and return types. No missing information for a tool of this complexity.

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

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

Schema coverage is 0%, but description explains the purpose of lat, lon, and radius (in meters). Adds value over raw schema by providing semantic meaning and units.

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 'Find WMATA bus stops near a latitude/longitude', specifying verb, resource, and criteria. Distinguishes from sibling tools like bus_routes and bus_route_details by focusing on stops near a point.

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

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

Implies usage for finding stops near coordinates with optional radius, but does not explicitly say when to use this vs alternatives or when not to use. Context signals show sibling tools for routes and incidents, but no direct 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 safe, non-destructive behavior. Description adds rich behavioral detail: data sourced from SEC EDGAR/XBRL and FAERS/FDA, handling of off-calendar fiscal years, sorted results, and inclusion of 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?

Single paragraph is information-dense but front-loaded with natural language examples. Could be slightly more structured (e.g., bullet points), but every sentence adds value and length is appropriate for the complexity.

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

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

Given 2 parameters, no output schema, and presence of annotations, the description fully covers purpose, usage, data, and output format. It leaves no critical gaps for an agent to make an informed decision.

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 (100% coverage). Description adds value by explaining data sources per type and providing concrete examples for values (tickers/CIKs vs drug names). This surpasses schema alone but schema already does most of the work.

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 explicitly states the tool does side-by-side comparison of 2-5 companies or drugs, using clear verbs like 'compare' and specifying resource type. It distinguishes from siblings like 'entity_profile' by emphasizing aggregation and efficiency.

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

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

Description includes explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete use-case examples ('which is bigger/better') and explains when each entity type is appropriate, with data sources clearly outlined.

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 readOnly, openWorld, idempotent, non-destructive. The description adds expected latency (15-60s), returns a detailed findings packet with evidence, confidence, sources, citations, and explicit gaps. No contradiction with annotations.

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

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

The description is lengthy but well-structured: account info first, then core function, usage guidance, and expected output. Uses bold, caps, and bullet-like structure. Every sentence adds value, though could be slightly tightened.

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 compensates by detailing the findings packet structure. Covers prerequisites (account, paid plan), alternatives, and latency. For a complex tool, it provides sufficient context for agent invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning: explains depth options by number of facets (quick=3, standard=5, thorough=8) and states default ('standard'). Clarifies that question can be broad/multi-part.

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

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

The description explicitly states the tool performs grounded multi-source research across 1242 structured data sources, distinguishes it from open-web search, and contrasts with siblings like ask_pipeworx for single lookups or current news. Uses specific verbs like 'decomposes', 'routes', and 'returns'.

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?

Clearly specifies when to use deep_research (multi-part, structured data) vs. ask_pipeworx (single lookup, breaking news). States account requirement and free option, and that 'thorough' depth needs a paid plan. Offers alternative if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by explaining what the returned results contain (full schemas with examples, ready to call). No contradictions.

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

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

The description is approximately 4 sentences, well front-loaded with the main purpose. Each sentence adds context. Could be slightly more concise, but overall efficient.

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

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

Given the complexity (discovering many tools) and the lack of output schema, the description adequately covers what the tool does, what it returns, and when to use it. It integrates well with the sibling list by positioning itself as a first-step tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions that query accepts natural language and has aliases, but this is already detailed in the schema. No additional semantic meaning beyond what the 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?

The description clearly states 'Find tools by describing the data or task.' and enumerates numerous domains (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by being a meta-tool for discovery, and it specifies the output: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use this tool versus alternatives, which is particularly useful given the long list of sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out across multiple sources, notes that the patents API sunset in May 2025 and soft-fails, and describes the return structure in detail. 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 but is efficiently front-loaded with examples and usage priority. It contains no filler, though it could benefit from minor structural separation (e.g., bullet points for output fields). Every sentence adds value.

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

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

Given no output schema, the description comprehensively covers the return structure (cik, company_name, filings, fundamentals, patents, news, LEI) and includes limitations (patents soft-fail). It also addresses input constraints. The tool's complexity is fully documented.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining that names are not supported (use resolve_entity), providing example values ('AAPL' or zero-padded CIK), and clarifying that 'type' is only 'company' for now. This goes beyond what the schema alone conveys.

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

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

The description clearly states that the tool provides a full cross-source profile of a US public company in one parallel call. It distinguishes from chaining single-pack lookups and lists the specific data sources and output fields. The purpose is unambiguous, with a specific verb ('profile') and resource ('US public company').

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 SEC/XBRL/news lookups when the user asks for a holistic view.' It also states that names are not supported and directs to use resolve_entity first. Clear when-to-use and when-not-to-use guidance, with a sibling alternative named.

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 behavioral context beyond annotations by noting that the tool clears 'sensitive data' and is used for 'stale context'. Annotations already indicate destructiveness and idempotency, so the description enriches understanding without contradiction.

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

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

The description is extremely concise, using two sentences to cover purpose, usage scenarios, and sibling relationships. No unnecessary words or 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?

Given the simple interface (one required param, no nested objects, no output schema), the description provides sufficient context for an AI agent to use the tool. It lacks explicit return behavior, but the simplicity makes this acceptable.

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

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

The input schema already has full coverage (100%) with a clear description for the 'key' parameter. The tool description adds no additional semantic detail beyond mentioning 'by key', so the baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key', making the tool's purpose unambiguous. It also pairs with sibling tools 'remember' and 'recall', providing context on its role in the workflow.

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

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

The description explicitly provides three concrete use cases: when context is stale, task is done, or to clear sensitive data. It does not explicitly state when not to use the tool, but the positive guidance is clear.

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

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

The description discloses key behavioral traits beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. It does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint). It adds operational context but could mention potential timeouts or size limits for larger sites.

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-loading the main purpose and then explaining the process and use cases. Every sentence adds value without unnecessary detail. 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 the tool's simplicity (2 parameters, no output schema), the description is complete. It explains the output format (single text blob drop at site-root/llms.txt) and covers typical use cases. No additional information is needed for an agent to use it effectively.

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

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

Schema coverage is 100% for both parameters. The description mentions max_links default and max, but this information is already present in the schema description. The description adds no new semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, specifying the verb 'generate' and the resource. It distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than checking or scanning.

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 specific use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), providing clear guidance on when to use. However, it does not explicitly mention when not to use or alternative tools, which would elevate it to a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field details but no additional behavioral context like pagination or rate limits. 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?

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. 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?

Covers purpose, return fields, when to use. Lacks description of params field structure but overall sufficient for a simple list tool with good annotations.

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

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

Schema coverage is 100% with description for include_inactive parameter. Description reiterates default behavior but adds no new semantic 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?

Explicitly states the verb 'List' and the resource 'caller's active subscriptions' and lists specific return fields. Clearly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides clear usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not mention exclusions but context is sufficient.

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

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

Annotations are all false, but description adds critical behaviors: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that team reads digests daily. 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 comprehensive but slightly redundant (e.g., 'broken, missing, or needs to exist' then later enumerated as 'bug, feature/data_gap, praise'). However, it is well-structured, front-loaded with purpose, and every sentence adds value.

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

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

Given the simplicity of a feedback tool and no output schema, the description covers all necessary aspects: usage context, content guidelines, behavioral constraints (rate limits, cost), and integration with roadmap. 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% but description enhances each parameter: explains enum values in context, provides guidance on message format (1-2 sentences, 2000 chars max), and clarifies that context fields are optional. Adds significant value beyond schema.

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

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

The description clearly states the tool is for sending feedback about broken/missing/needed functionality. It enumerates specific use cases (bug, feature/data_gap, praise) and distinguishes from sibling tools like ask_pipeworx or bus tools by focusing on feedback.

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

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

Explicitly provides when to use: wrong/stale data (bug), missing tool (feature/data_gap), positive experience (praise). Also specifies what not to do ('don't paste the end-user's prompt') and includes rate limits (5/identifier/day) and quota info.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context: 'Self-aggregating signal', 'derived from CF analytics-engine, no PII', and 'Cached 5min-1h depending on window'. This discloses data provenance, privacy, and caching freshness, going 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 a single paragraph but efficiently structured: main output, then three use cases as inline list, then provenance and caching details. Every sentence adds value—no fluff, front-loaded with the most important information (what it returns).

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers all necessary aspects: outputs, use cases, data source, privacy, caching, and parameter semantics. The agent has enough to decide when and how to invoke it correctly.

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

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

Schema covers 100% with a single optional 'window' parameter. Description explains semantic difference: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the enum values, guiding the agent on which window to choose based on the need.

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 specifies the tool returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)', clearly stating the verb (returns), resource (aggregated trends), and scope (from AI agents on Pipeworx). This distinguishes it from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on aggregate call data rather than prompting or static discovery.

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

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

Explicitly lists three use cases: (1) discovering hot data sources, (2) confirming popular tools, (3) assessing alignment with agent needs. This tells the agent when to use the tool. However, it does not mention when not to use it or provide alternatives, though the context is clear enough for a trending 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?

Annotations indicate safe, idempotent, read-only behavior. Description adds extensive behavioral details: partition check (sum≈1, >3pp deviation signals), semantic anchor (Jaccard≥0.30), partition filter (placeholder slugs), fill check (realizable vs theoretical edge). No contradiction with annotations.

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

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

Description is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. However, it is somewhat verbose (~250 words). Could be slightly shortened without losing clarity.

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

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

Given the tool's complexity (multiple modes, checks, response format) and no output schema, the description covers all necessary information: modes, parameters, behavioral details, response structure, and sibling references. An AI agent can confidently select and invoke this 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%. Description adds meaning beyond schema: explains default behavior, gives examples for event ('fed-decision-may-2026') and topic ('Fed rate decision'), and clarifies cross-event scanning. Provides context for no-args 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges, polymarket_fill_risk, etc.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for trending_scan... pass event for strongest per-event partition_check, or topic for themed cross-event scan.' Recommends event for specific markets and mentions polymarket_fill_risk for custom sizing.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavior: caching at KV level for 1 hour, model families with detailed logic (e.g., partition_overround with sport-specific alpha), response structure including diagnostics, and tradeable-edge filters. 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 very long and detailed, covering many technical specifics. While well-structured with sections for segments and knobs, it could be more concise without losing essential information. The first sentence effectively front-loads the 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 of 9 parameters, no output schema, and detailed model logic, the description is exceptionally complete. It explains response structure, diagnostics, fed bets exclusion, caching, and parameter interactions. Agents have sufficient context to use the tool effectively.

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

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

Schema coverage is 100% with parameter descriptions. The description adds further context, explaining how knobs like min_liquidity and max_spread_pp serve as tradeable-edge filters, and clarifies the distinction between min_kelly and min_partition_leg_kelly for different opportunity types.

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

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

The description states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, clearly defining the verb and resource. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on disagreement with Pipeworx data.

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

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

The description frames the tool as 'what should I bet on today' and explains it avoids paging hundreds of markets. It details the three segments and provides context for filtering knobs, but does not explicitly state when not to use it or compare to siblings like polymarket_arbitrage.

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. The description adds significant behavioral context: snapshots written on cache-miss, gaps mean no scan, decay from daily closes not intraday, 60-day TTL limit. This goes well beyond annotations.

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

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

The description is fairly long but well-structured, front-loading purpose and then detailing response fields. Some phrasing (e.g., 'the latter is wide for a reason nobody is willing to take') adds color but is not essential. Slightly verbose but effective.

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

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

Despite no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and covers edge cases like gaps and limits. For a tool with two optional parameters and complex time-series output, this is complete.

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

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

Schema coverage is 100% (both parameters described). The description adds meaning: days default 14 max 30 (schema says clamp 2-30), window default '1wk', and explains the response structure in detail, compensating for lack of output schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' built from daily snapshots. It answers a specific question about edge age and decay, distinguishing it from sibling tools like polymarket_edges (raw edges) and polymarket_arbitrage (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 explains when to use: to understand if an edge is new or stale. It doesn't explicitly state when not to use, but the context and sibling list imply it's for historical persistence rather than current edges or arbitrage, providing adequate guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds behavioral details like walking the ladder, returning verdicts (clean|degraded|cannot_fill), and listing return fields. It does not contradict annotations and provides additional context beyond what annotations offer.

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

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

The description is detailed but well-structured: first sentence states core purpose, then REQUIRES clause, then bullet-like explanations for both modes. Every sentence adds value, though the length is justified by tool complexity. No wasted words.

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

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

Despite no output schema, the description fully enumerates return fields for both modes, covers edge cases (thin legs, forced directional risk), and explains why this check is critical. Given the tool's complexity and zero output schema, the description is complete enough for correct agent usage.

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 4 parameters. The tool description enhances this by clarifying mode selection (market vs event), default values, and interpretation of size_usd for buys vs sells. It adds high-level context not present 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 checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before them.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about risks of partial fills converting arb to unhedged positions, giving clear when-to-use and when-not-to-use context.

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

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

The annotations already indicate read-only and idempotent behavior. The description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, spreads, top_spreads_pp), safety fields (compatibility_warning conditions, temporal_alignment, skipped counters). It also explains that pre-mapped topics often return warnings and that real spreads are rarer than suggested. This significantly enriches transparency beyond annotations.

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

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

The description is lengthy but well-structured: it starts with the core concept, then details modes, response, and safety fields. Every sentence provides distinct information. However, it could be slightly more concise, as some details (like the skipped counters explanation) could be shortened without losing meaning.

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

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

Despite having no output schema, the description thoroughly explains what the response contains: each venue's leg-by-leg prices, spread data, compatibility_warning, temporal_alignment, and skipped counters. This gives the agent a complete picture of the tool's behavior and output format, making it highly usable.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the topic parameter as a list of 10 pre-mapped shortcuts, and the explicit parameters as overrides. It provides examples and clarifies that topics are just shortcuts. This goes beyond the schema's basic type and optionality.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread) and the resources (Kalshi and Polymarket), and distinguishes from sibling tools like polymarket_arbitrage which focuses on within-venue 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 explains two modes (topic shortcuts and explicit tickers) and provides guidance on when the output is meaningful via safety fields (compatibility_warning, temporal_alignment). It warns that most pre-mapped topics yield warnings, helping the agent manage expectations. However, it does not explicitly contrast with sibling tools or state 'use this tool when you need cross-venue comparison.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, ensuring the agent knows it's a safe read operation. The description adds value by specifying the exact output fields (incident description, affected lines, etc.), which is helpful 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 two sentences with no extraneous information, directly stating the action and the return fields. It is 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 the tool's simplicity (no parameters, output schema exists), the description is complete. It tells the agent what the tool does and what it returns, which is sufficient for correct usage.

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 tool has zero parameters, and the schema coverage is 100%. The description does not need to add parameter information. It effectively describes the output, making the intent 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 uses a specific verb 'Fetch' and specifies the resource 'current WMATA Metro rail service alerts and incidents', clearly distinguishing from sibling tools like bus_incidents.

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 states what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., bus_incidents) or when not to use it. However, given the simplicity and lack of parameters, this is a minor 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context on returned fields but does not disclose additional behavioral traits like rate limits or authentication requirements.

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 sentence, no fluff. Directly states purpose and output fields. Front-loaded with 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?

For a simple list tool with an output schema and no parameters, the description is complete. It lists the returned fields and scope, requiring no further explanation.

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

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

No parameters exist, so schema coverage is 100%. Description is adequate and receives baseline 4 per scaling guidelines for zero-parameter tools.

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 all WMATA Metro rail lines with specific fields (line code, display name, start/end station codes, internal track IDs). It distinguishes from sibling tools like rail_incidents and rail_predictions by focusing on static line data.

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

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

The description implies usage for retrieving static line data but does not explicitly state when to use this tool over siblings (e.g., rail_stations, rail_incidents). No when-not or alternative guidance 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?

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds that it returns line, destination, car count, and minutes. Does not contradict annotations, but adds modest context beyond what annotations provide.

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

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

Single sentence, no redundancy, front-loaded with action and resource.

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 with 1 param and output schema, description covers purpose, input format, and return fields. Complete for AI agent to 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%, but description explains param format ('comma-separated station_codes') and special value ('All'). This is essential for correct 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?

Description uses specific verb 'Fetch' on resource 'real-time next-train arrival predictions' with clear scope (one or more stations, comma-separated or 'All'). Distinct from sibling tools like rail_incidents, rail_lines.

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 explicit when-to-use or when-not-to-use guidance. No alternatives mentioned. Implies usage for predictions but fails to differentiate from bus_predictions or other rail tools.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds that the tool returns specific fields (name, address, line codes, etc.), which is consistent and slightly enhances transparency but goes beyond annotations.

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

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

The description is succinct, with two sentences. The first sentence states the core action and parameter. The second lists outputs. 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?

Given the presence of an output schema (not shown), the description adequately covers the behavior. It explains the single required parameter and the return fields, and the sibling context differentiates from rail_stations.

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 0% description coverage for parameters. The description mentions 'by station_code' and the schema provides examples (e.g., 'A01'), adding minimal semantics. A more explicit description of station_code format would be better, but the examples help.

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 ('Fetch details'), the resource ('specific WMATA Metro station'), and the input parameter. It also lists the returned fields, distinguishing it from the sibling tool 'rail_stations' which likely lists all stations.

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

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

The description implies use for a single station by station_code, but does not explicitly contrast with sibling tools or provide when-to-use/not-to-use guidance. No alternatives mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by detailing return fields (station code, name, line codes served, latitude/longitude), which complements 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, no filler, front-loaded with purpose and optional filter. Every word earns its place. Excellent conciseness.

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

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

Given simplicity (1 optional param, output schema exists), description covers core purpose, filter, and return fields. It doesn't mention pagination or limits, but for a likely small dataset, this is adequate. Output schema handles detailed return structure.

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

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

Schema coverage is 0% (no parameter descriptions in schema), but description explains that line_code is an optional filter. This adds semantic meaning beyond the schema's type definition. The schema examples also hint at usage, but description solidifies it.

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

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

Description clearly states the tool returns all WMATA Metro rail stations, optionally filtered by line_code. The verb 'Return' and resource are specific. It distinguishes from sibling tools like rail_station_info (single station details) and rail_lines (lines list).

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

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

Description indicates filtering option ('optionally filtered by line_code'), providing clear context for when to use. No explicit exclusions or comparisons to siblings, but the optional filter and explicit listing purpose imply usage 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and explains the listing behavior when omitting the key. 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 just two efficient sentences, front-loaded with the core purpose, and 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?

With only one optional parameter, no output schema, and annotations covering safety, the description is complete: it explains all behaviors, scoping, and pairing with other 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 provides 100% coverage with a clear description for the 'key' parameter. The description adds the semantic nuance that omitting the key lists all saved keys, which goes beyond what schema says.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the resource (memory key/value) and distinguishes 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?

The description provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget, though it 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable context: returned fields (source, citation_uri, payload), mark_read behavior, polling suitability, and alternative HTTP access. 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?

Concise paragraph, front-loaded with core purpose. No fluff, but the mention of alternative HTTP access could be considered extraneous for tool selection. Nearly 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?

With no output schema, description covers key aspects: return fields, filtering, mark_read effect, polling. Missing explicit note on limit and unread_only parameters, but still fairly complete for a read-only retrieval tool with good annotations.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples (e.g., type 'sec_8k') and explains mark_read behavior, but doesn't explicitly cover limit and unread_only. Baseline 3 is appropriate.

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

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

Clearly states it pulls fired events from subscription feed, returning alerts with specific fields. However, does not explicitly distinguish from sibling tools like 'recent_changes' or '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?

No explicit guidance on when to use this tool versus alternatives. The mention 'Polls work fine' implies suitability for polling but does not compare to other tools or 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 goes well beyond annotations: it details the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), behavior on rate limits (GNews fallback) and API sunset (soft-fail), and return structure (changes grouped by source, total_changes, 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 detailed but well-structured with examples and clear segmentation of sources. While some might find it slightly verbose, every sentence earns its place, and the front-loaded examples quickly orient the agent.

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

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

Given no output schema, the description compensates by specifying the return format (changes grouped by source, total_changes, citation URIs). It covers all parameters, sources, edge cases (fallback, soft-fail), and usage context. Nothing essential is missing for a complex tool.

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

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

Schema has 100% coverage, but the description adds value: explains 'since' can be ISO date or relative shorthand with examples, suggests '30d' or '1m' for typical monitoring, and clarifies 'value' accepts ticker or CIK. This enhances usability 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 identifies it as a change feed for a company across SEC, news, and patents, with specific example queries. It distinguishes from the sibling 'entity_profile' tool by explaining that entity_profile is for static profiles, 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?

Provides explicit guidance to use 'entity_profile' for static profiles instead, and includes example queries showing when to use this tool. However, no exclusions for other tools (e.g., for specific news or SEC filings alone) are mentioned, limiting completeness.

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

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

Beyond the annotations (idempotentHint, destructiveHint), the description adds behavioral context: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This clarifies storage behavior and session limits.

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

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

The description is concise (4 sentences) and front-loaded. The first sentence defines purpose, followed by usage guidance and storage specifics. Every sentence serves a purpose 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?

For a simple memory tool with full schema coverage and annotations, the description is complete. It explains storage mechanism, persistence rules, and pairing with recall/forget. 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 description coverage is 100%, so baseline is 3. The description does not add extra meaning to the parameters beyond what is already in the schema descriptions. It is sufficient but not enhanced.

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: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It specifies the verb 'save' and the resource 'data' for reuse, and distinguishes it from siblings by mentioning 'recall' and 'forget'.

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

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

The description explicitly advises when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names complementary tools (recall, forget), though it does not provide 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?

Annotations already declare readOnly, openWorld, idempotent. Description adds that the tool internally cascades through several endpoints, replacing 2-3 lookups, and mentions auto-disambiguation. No contradictions, but could elaborate on disambiguation edge cases.

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 moderately long but efficient—every sentence serves a purpose. Front-loaded with example queries aids quick scanning. Could trim some internal detail, but overall 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?

Despite no output schema, description fully explains return values per type and input formats. Covers supported types, internal cascading, and citation URIs. With strong annotations, this is complete for an agent to select and 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?

Schema coverage is 100%, but description adds significant meaning: details what each type returns (ticker+CIK+URI vs. RxCUI+ingredient+brand+URI), input flexibility (ticker, CIK, name), and auto-disambiguation—all beyond the schema's enum and string 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 clearly states the tool resolves names to official identifiers, with example queries that match common user intents. It distinguishes from siblings like entity_profile by focusing on identifier resolution rather than profile enrichment.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID'. Mentions it replaces multiple manual lookups, but does not explicitly contrast with siblings or 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?

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density, and notes the conditional _apiKey requirement for anthropic model. 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 with no fluff. Front-loaded with the core purpose, followed by a usage example and output description. 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?

With 4 parameters (1 required), no output schema, and comprehensive annotations, the description fully explains input and output. It covers the workflow (probes each entity, ranks) and result fields (score, confidence, signal density). No gaps.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds contextual meaning: 'entities' first entry is the 'subject', 'models' has default, and 'context' disambiguates common names. This goes beyond the schema by explaining the role of each parameter in the comparison workflow.

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

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

The description explicitly states the tool compares AI visibility across multiple entities side-by-side, ranks them by score, and identifies most/least recognized. This clearly distinguishes it from the sibling tool 'ai_visibility_check' which checks a single entity.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use (comparison scenarios) but does not explicitly state when not to use or list alternatives, though the context of multiple entities inherently differentiates 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, openWorldHint, idempotentHint, and destructiveHint. The description adds crucial behavioral context: the tool fans out across two services, returns a specific summary block, includes per-advisory details, and mentions that bundlephobia's first measurement can take 5-30 seconds with graceful degradation via sources_failed. No contradiction with annotations.

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

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

The description is two sentences long, starting with the core purpose then systematically covering checks, usage conditions, return structure, and limitations. Every sentence earns its place with no redundancy or 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 complexity (two external services, multiple data points, partial failure handling), the description fully covers what the tool does, what it returns (summary block, per-advisory detail, links, alternative versions), ecosystem limitations, and potential delays. Although there is no output schema, the description compensates by explicitly listing return fields.

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

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

With 100% schema description coverage, the schema already documents both parameters well. The description adds extra value by noting that scoped packages are accepted and that version defaults to the latest when omitted, providing practical usage nuance 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 a specific verb ('scan') and resource ('npm package dependency'), clearly stating it performs a composite check by fanning out across deps.dev and bundlephobia. It distinguishes from siblings by noting the npm-only scope in v1 and directing other ecosystems to deps.dev:version directly.

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: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also provides a clear when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps the agent decide between this tool and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and truncation behavior (200K char cap with flag). 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, well-structured paragraph. Every sentence adds value: purpose, usage guidance, behavioral details, and pairing information. It is front-loaded with the core purpose and contains no redundant or extraneous information.

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

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

Despite the absence of an output schema, the description fully explains the return value: 'top-N passages with character offsets and similarity scores.' It also covers constraints (200K char limit) and pairing with another tool, making the definition complete for agent decision-making.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains how to use each parameter: 'Pass the text you already pulled' for 'text', 'natural-language query' with examples for 'query', and specifies the range and default for 'limit' (1-20, default 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 the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search' and the resource ('a fetched record/text'). It distinguishes from siblings like 'ask_pipeworx_grounded' by explicitly mentioning them as paired tools, avoiding confusion.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also suggests pairing with 'ask_pipeworx_grounded' and explains the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This fully addresses usage context and alternatives.

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

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

Discloses behavioral traits beyond annotations: requires OAuth, returns subscription id, supports multiple types, webhook HMAC signing and auto-disable after 10 failures. No contradictions with annotations (idempotentHint=true is consistent with safe retry).

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

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

Well-structured with front-loaded purpose. Slightly long but every sentence earns its place. Could be more concise (e.g., grouping type examples), but clarity is maintained.

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 3 parameters and no output schema, description covers return value (subscription id), prerequisites, type behaviors, delivery options, and edge cases (auto-disable, secret lifetime). Complete for a subscription creation 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?

Adds meaningful context beyond schema: type-specific param examples (e.g., items codes for sec_8k, min_spread_bps for polymarket_edge), delivery validation requirements (phone verification, webhook signing secret). Schema coverage is 100% so baseline is 3, but description adds significant 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?

Description states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource and clearly distinguishes from sibling tools like list_subscriptions or unsubscribe.

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

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

Provides detailed usage context: requires Pipeworx OAuth account, lists supported types with examples, delivery channels, and limits (10/day SMS). Lacks explicit when-not-to-use but contrasts with anonymous/BYO accounts.

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 safe, read-only, idempotent behavior. The description adds context about being an onboarding entry point and that it returns example questions drawn from the live catalog, which is valuable 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 long but well-structured, front-loading common user queries. Each sentence serves a purpose, though it could be slightly more concise.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description fully explains the output and usage context. It provides enough detail for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of the topic parameter and listing example values, 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 it is the onboarding entry point for a new agent to discover what questions to ask Pipeworx. It specifies the return type (category-bucketed example questions with tool+argument shape) and distinguishes from siblings by being the first call to understand capabilities.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to pass the topic argument. It also mentions it can help learn how to call meta-tools, giving clear context for 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?

Adds meaningful behavioral info beyond annotations: ownership enforcement, deactivation (not deletion), historical data retention. 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, no fluff, front-loaded with core action. 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 1-param tool with annotations, description covers behavior, constraints, and side effects completely.

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

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

Schema coverage 100%, description for parameter id is clear. Description adds no extra semantic value beyond schema, baseline 3.

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

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

Clear verb+resource: 'Cancel a subscription by id.' Distinguishes 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?

States usage context: ownership enforced, deactivation vs deletion. Lacks explicit when-not-to-use or alternative tools, but clear enough.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds domain limitation (v1 supports company-financial claims), output format (verdict types, citation, delta), and explains it replaces multiple calls. 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 with trigger phrases, then provides usage, domain, returns, and efficiency gains. Every sentence adds value, though slightly verbose with multiple examples.

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 and no output schema, the description adequately covers purpose, when to use, domain, return values, and efficiency. It is complete for a specialized tool.

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

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

Schema coverage is 100% with a clear description of the claim parameter. Description enhances understanding with examples and clarifies the natural-language nature, going beyond the schema.

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

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

Description clearly states it is for natural-language claim verification against authoritative sources, with specific examples of trigger phrases and domain (company-financial claims). It distinguishes itself from siblings by noting it replaces multiple sequential calls.

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 factual correctness of a user's claim. Provides domain scope (company-financial claims) but does not explicitly state when not to use it or suggest alternatives.

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