Maptiler

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

Discloses return structure (per-model score/confidence/signals/raw_response and combined view), API key handling, and cost implications. Complements annotations (readOnlyHint, etc.) with practical 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?

Three sentences, front-loaded with main action, no filler. Every sentence adds distinct 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 tool with no output schema, the description adequately explains return format, preconditions (API key), and typical use cases. No gaps identified.

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. Description enriches with examples (entity types, default model) and clarifies _apiKey usage, adding 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?

Explicitly states the tool probes LLMs for knowledge and scores visibility per model. Differentiates from sibling tools like deep_research by focusing on AI visibility audits.

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 use cases (AI-marketing audits, brand checks, competitive monitoring) and explains model selection. Lacks explicit 'when not to use' but still actionable.

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

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

With all four annotation hints already present (readOnly=true, openWorld=true, idempotent=true, destructive=false), the description still adds substantial behavioral context: it discloses the internal routing architecture (5,566 tools across 1,462 sources), the auto-fill behavior, the stable pipeworx:// citation URI return format, and platform/performance details ('works on every tier, one fast call'). The description is fully consistent with the annotations — a read-only, open-world, idempotent query tool. No contradiction.

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

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

The content is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and logically progresses from what → when → step-up alternatives. However, it repeats the same 'I am the default/preferred tool' signal at least four times ('PREFER OVER WEB SEARCH', 'USE WHENEVER', 'START HERE... default entry point', 'step up only when needed'), and the entire thing is a dense, unbroken wall of text with no bullets or paragraph breaks. Every idea earns its place, but the redundancy and lack of formatting stop it from being truly well-structured.

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

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

For a meta-router of this complexity, the description is remarkably thorough: it covers the decision boundary with web search, names and explains the escalation path to two sibling tools, discloses internal behavior (routing, argument filling, citation URIs), acknowledges the news/breaking-edge case, and includes six realistic examples. Although there's no output schema to offload return-format documentation, the description still communicates the output shape (structured answer with pipeworx:// citation URIs). Nothing material is missing for an agent to decide when and how to 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?

The input schema is exhaustively documented with 100% coverage (all six parameters are aliases of the same natural-language 'question' argument, and the schema explains the alias behavior). Per the rubric, high schema coverage sets the baseline at 3. The description adds meaningful usage semantics above baseline through six concrete example phrasings and by clarifying that the input should be a self-contained real-world question ('current US unemployment rate', 'patents Tesla was granted last month'), which trains the agent on desired input format beyond the schema's dry 'Your question or request in natural language.'

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?

Uses a specific verb+resource structure ('PREFER OVER WEB SEARCH for questions about current or historical data') followed by a concrete domain list (SEC, FDA, FRED/BLS, USPTO, etc.) and a clear mechanism (routes to 5,566 tools, fills arguments, returns pipeworx:// citations). It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research directly as escalation paths, making the tool's distinct role unmistakable.

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

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

Provides explicit when-to-use guidance: trigger phrases ('what is', 'look up', 'find', 'get the latest'), preferences over web search, and clear exclusions naming specific alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). Even addresses an edge case (breaking news) and explains why this tool already covers it. This is textbook when/when-not/alternatives 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 destructiveHint=false. The description adds dynamic behavior: routing improvements are enabled live when under test, currently no candidate is active, and it is a full router with no fallback. It also discloses that results are compared against the stable router for merge decisions.

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 four sentences, front-loaded with the tool's identity as a beta. It includes useful context but has some redundancy, such as 'Falls back to nothing — this IS a full working router' which could be trimmed.

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?

It explains the tool's relationship to ask_pipeworx, its experimental nature, current state, and response shape, which is sufficient for a beta variant of a known tool. It lacks examples of how to phrase a question, but the schema and sibling context fill that gap.

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

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

Schema coverage is 100% and the description only mentions 'same arguments' without adding details. The schema already documents the question parameter and aliases, so the description adds no parameter semantics beyond structured data.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,566 tools, arguments, and response shape. It distinguishes from the stable sibling tool (ask_pipeworx) by noting candidate routing improvements.

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

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

It explicitly tells users to use it like ask_pipeworx when they want the newest routing, and notes that no candidate is currently active so it exactly matches the stable version. However, it does not explicitly state when not to use it (e.g., for stability), so it falls short of full exclusion 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?

Despite comprehensive annotations (readOnlyHint: true, destructiveHint: false), the description adds substantial behavioral context: the extraction logic (pulling only from the tool result), the exact success payload structure, and the full enumeration of partial-failure refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). The 'costs one extra LLM call' disclosure is exactly the kind of operational transparency beyond annotations that the rubric rewards.

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?

Remarkably information-dense yet parses cleanly: the four major ideas (what it does, the guaranteed return shape, when to use it, when not to) each get exactly one sentence in a logical escalation. Every clause ('fetches the data', 'fills arguments', 'Costs one extra LLM call') is load-bearing and the whole description reads front-loaded with the most important semantic distinction first.

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 tool whose sole input is a natural-language question with no output schema, this description is complete: it covers input aliases, execution behavior, the structured output shape, failure modes, and cost implications. The comparison against ask_pipeworx closes any remaining gaps about expected return values or 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?

The description does valuable work alongside a well-covered schema. It confirms that the primary semantic parameter is the natural-language question while also documenting the aliases (query, q, prompt, text, input) that the schema mentions. It enriches understanding by revealing the question likely goes through tool-routing across 5,566 tools across 1462 sources, providing context no schema description could capture.

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?

This description is exemplary: 'Hallucination-resistant answer mode for high-stakes reads' uses a specific verb-plus-resource construction while immediately establishing the tool's differentiator. It explicitly names the sibling ('Same routing as ask_pipeworx') and thoroughly distinguishes itself from the broader family through its extracted-answer contract and refusal behavior.

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 comprehensive usage guidance: it explains when to use this tool ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), provides concrete use-case examples (financial verdicts, legal claims, medical lookups, public statements), explicitly names the alternative ('prefer ask_pipeworx for casual lookups'), and even discloses the cost differential ('Costs one extra LLM call').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: resolution process (resolver contract with confidence levels, alternatives, suggestions), fan-out logic, safety short-circuits (low-confidence, closed markets, wide spreads), cancellation rule parsing, and response shapes. 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 verbose but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and input examples. Some detail (e.g., all fan-out examples) could be condensed, but the structure aids readability.

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

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

No output schema, so description carries full burden. It thoroughly explains all return fields (market, analysis, evidence), including edge cases (low-confidence match, closed markets, wide spreads, cancellation rule, parent event extractor, news fields with fallback info). Given tool complexity, description is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters work in practice (e.g., default depth is 'thorough', include_raw=false for compact responses). It does not repeat schema details but provides usage context that aids agent invocation.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb ('Research'), resource ('Polymarket bet via Pipeworx data'), and scope ('in one call'). It provides input examples and distinguishes from sibling tools like polymarket_edges or deep_research by focusing on full evidence packet generation.

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

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

The description lists explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives detailed fan-out examples per bet category. However, it lacks explicit when-not-to-use guidance or direct comparisons to alternatives like ask_pipeworx or deep_research.

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

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

The description reveals behavioral details beyond annotations: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), mentions sorting by primary metric, and notes off-calendar fiscal year handling. Annotations already mark it as read-only and idempotent, and the description adds no contradictions.

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

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

The description is concise yet comprehensive, front-loading trigger phrases and then providing structured details. Every sentence adds value: use guidance, type-specific behavior, sorting, and efficiency claim. No filler or repetition.

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

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

Given the tool has only 2 parameters (type, values) and no output schema, the description fully covers input constraints, behavior for each type, result ordering, and citation output. An agent can invoke this tool correctly without additional context.

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

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

The schema covers 100% of parameters, but the description adds rich context: examples for values (tickers/CIKs for company, drug names), explains what each type returns (revenue/net income/cash/debt vs. adverse-event/FDA/trial counts), and specifies min/max limits. This goes well beyond the schema's type descriptions.

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

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

The description clearly defines the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses specific action verbs like 'compare', 'rank', and 'head-to-head', and distinguishes it from siblings like 'entity_profile' by explicitly stating it replaces multiple sequential lookups.

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

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

The description provides explicit guidance on when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It includes example query triggers and specifies the number of entities (2-5) and types (company/drug), leaving no ambiguity about appropriate 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=true, idempotentHint=true, destructiveHint=false. The description adds context about the type of conversions (e.g., to Web Mercator, UTM) but does not discuss behaviors like input validation or error handling. It does not contradict annotations.

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

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

The description is a single sentence with parenthetical aliases, front-loading the main purpose. It is concise with no wasted words.

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

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

With 2 simple parameters and no output schema, the description provides enough to understand the tool's purpose but lacks details on coordinate format and EPSG code conventions. The schema examples partially compensate, but completeness is average.

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

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

Schema coverage is 0%, and the description does not explain the parameters. It mentions lat/lng and target CRS but does not specify coordinate order (lng, lat) or that target_crs is an EPSG code. The schema examples provide some help, but the description adds little meaning beyond the schema.

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

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

The description clearly states the tool converts WGS84 lat/lng to other CRS, uses multiple aliases like 'reproject coordinates' and 'EPSG:4326 → EPSG:[X]'. It distinguishes from sibling tools by focusing on CRS conversion, unlike geocoding or elevation tools.

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

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

The description explains when to use the tool (to convert standard lat/lng into projected systems) and gives specific examples like Web Mercator, UTM zones, state plane. It does not explicitly mention when not to use or provide alternatives, but the context is clear enough for typical 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses authentication and paid-plan requirements, parallel tool routing, findings packet structure, gaps[] behavior, contradictions[], citation resolution semantics, hop fields, semantic excerpting, and latency. It also warns about empty gaps results when the topic is not in the structured catalog.

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

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

The description is dense and impactful but somewhat long and stream-of-consciousness. Every sentence carries meaningful information, including auth, use cases, internal mechanics, output details, citation behavior, and latency; however, some claims are repeated or could be tightened 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?

With no output schema, this description carries the full burden of explaining return values and operational behavior. It fully covers answer shape, sources, confidence, citations, gaps, contradictions, grounding guarantees, latency, downstream fetchability, and large-record truncation, making it complete for a complex research tool.

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

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

The schema already covers both parameters at 100%, but the description adds useful depth-level semantics: standard re-angles unanswered gaps while thorough chases best leads and adds contradiction detection. It also clarifies that the question can be broad and multi-part, which is important guidance beyond the raw 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 gives a specific action and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and clearly explains that it is not open-web search. It differentiates from siblings by positioning this as the broad/multi-part parallel research tool while naming ask_pipeworx as the single-lookup alternative.

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

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

It explicitly states when to use the tool ('Best for broad/multi-part questions over structured data'), when not to use it ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even handles authentication fallback. The depth-level guidance also explains when standard vs thorough iteration is appropriate.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which the description aligns with. It adds behavioral details such as returning 'full input schemas (with curated examples)' and that results are 'ready to call directly,' providing value beyond annotations. No contradictions, but some aspects like error handling are omitted.

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

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

Four sentences, each contributing unique value: purpose, domain list, return value with usage note, and strategic guidance. No redundant information. Perfectly 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 no output schema, the description explains the return format (names, descriptions, schemas, examples) and states they are callable immediately. This is sufficient for a discovery tool. Minor omissions (e.g., error behavior) but overall complete for its complexity.

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

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

Schema coverage is 100% with all 6 parameters described. The description adds context about query aliases (task, q, description, search) and provides example queries. However, it does not add significant new meaning beyond what the schema already 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 'Find tools by describing the data or task,' specifying the verb and resource. It lists diverse domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools like deep_research or geocode by being a discovery tool. The purpose is unambiguous and well-defined.

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 to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides strong context for when to use it, though it lacks explicit statements about when not to use it. The guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds the data source (SRTM/Maxar), which provides context on coverage but does not disclose limitations like missing data areas or potential inaccuracies.

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 concise, using examples to convey purpose efficiently. However, it could be restructured to include parameter details without losing brevity.

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

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

Despite low complexity (2 params, no output schema), the description omits parameter descriptions and return structure. It only states the elevation value in meters, which is adequate for output but incomplete for input semantics.

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

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

Schema description coverage is 0%, so the description must compensate. It fails to mention the required parameters lat and lon or provide any format/range guidance beyond the schema's property names and types, which is insufficient for a 2-parameter tool.

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

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

The description clearly states the tool returns elevation in meters above sea level at a single point, with examples of natural language queries. However, it does not use an explicit verb like 'get' or 'retrieve', and the distinction from the sibling 'elevation_polyline' is implicit.

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 indicates single-point usage and contrasts with polyline by mentioning 'single point'. It implies the data source (MapTiler's SRTM/Maxar) but lacks explicit when-not or alternative 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, destructiveHint=false. Description adds behavioral context (returns elevation samples along polyline) but does not elaborate on output format or limitations. Adequate given annotation coverage.

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 with example queries and use cases, front-loaded with actionable phrases. Efficient, but could be more precise about coordinate order.

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 one parameter, no output schema, and annotations covering safety, the description is adequate for a simple read tool. However, it lacks coordinate order specification and output details, leaving some ambiguity.

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 one required parameter (coordinates) with 0% description coverage. Description says 'sequence of lat/lng' but example shows [lng, lat] order. This ambiguity and missing formal definition means the description adds limited value and may mislead.

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 'elevation samples along a polyline' and provides example use cases like hiking elevation gain, cycling grade, trail planning. It implicitly distinguishes from sibling tools like 'elevation' (likely single 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?

Provides explicit example queries and use cases ('Use for hiking elevation gain, cycling grade, trail planning'). No explicit when-not-to-use, but context is clear and distinguishes from polyline vs. point.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds specifics: fans out across multiple sources, returns detailed fields (cik, recent_filings with URIs, fundamentals, patents with sunset warning and soft-fail, news fallback, LEI). This behavior is transparent and trustworthy.

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

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

The description is dense but well-structured, starting with example queries and then systematically listing returned components. It is slightly long but each sentence adds value; could be tighter 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?

Given the tool's complexity (multiple data sources, fallbacks, no output schema), the description thoroughly explains inputs, outputs, limitations (patents sunset, name not supported), and return format. It is fully self-contained 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%; both parameters are already well-documented in the schema. The description repeats the name-not-supported note, but adds no new parameter semantics 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 the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists example queries. It distinguishes from siblings like resolve_entity which handles name resolution.

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' for holistic views, and warns that names are not supported—'use resolve_entity first'. Provides clear when-to-use and when-not-to-use guidance with named alternative.

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 destructiveHint=true and idempotentHint=true. Description adds minimal context about clearing sensitive data but does not elaborate on idempotency or other behaviors.

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

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

Two sentences with no wasted words. Front-loaded with action and resource, then usage guidance.

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

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

Given the tool's simplicity and no output schema, the description fully covers what the agent needs: purpose, when to use, and related tools.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description does not add additional meaning beyond schema.

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

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

Clear verb 'delete' with specific resource 'previously stored memory by key'. Distinguishes from siblings remember and recall explicitly.

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: stale context, task done, clear sensitive data. Also suggests pairing with remember and recall.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds detailed behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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: purpose, behavior, use cases. Front-loaded, no fluff, 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?

Output is described ('single text blob ready to drop at site-root/llms.txt'), parameter coverage is complete, and no output schema is needed. Addresses all likely agent questions.

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 value by specifying default and max for 'max_links' (default 25, max 50) and clarifying 'url' as full URL. Slightly improves upon schema alone.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. Uses specific verb 'generate' and resource 'llms.txt file', and distinguishes from sibling tools by its unique focus on AI crawler indexing.

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

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

Provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' Lacks explicit when-not-to-use or alternatives, but context with siblings implies specialization.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that results are ranked and include lat/lng, address components, and feature IDs, aligning with the annotations. No contradictions.

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

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

The description is a single paragraph that efficiently conveys purpose, usage patterns, and relationship to sibling. It is front-loaded with examples. Could be broken into bullet points but is reasonably 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?

With 9 parameters and no output schema, the description covers core functionality and return fields (candidates with components). It mentions re-lookup but lacks details on errors, empty results, or parameter combinations beyond examples. Adequate but incomplete.

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%, so description must compensate. It illustrates query, limit, proximity, fuzzyMatch via examples, but bbox, types, country, language, autocomplete are not explained. This leaves significant gaps.

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

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

The description clearly defines the tool as forward geocoding via MapTiler (OSM data), with explicit usage examples and differentiation from alternatives like Mapbox/Google. It also links to sibling tool geocode_by_id.

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 it's an alternative to Mapbox/Google when OSM data is desired, and mentions that results can be used with geocode_by_id. However, it does not explicitly compare to sibling geocode_reverse or coordinates_convert.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. Description adds functional context (re-fetching by stable ID) that aligns with these hints, reinforcing the safety profile 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?

Two tightly written sentences, front-loaded with the action. 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?

Given simple tool with 2 params, no output schema, and rich annotations, description covers purpose and usage but lacks parameter explanations. Adequate but could be enhanced by describing the 'language' parameter.

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

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

Schema has 0% description coverage for parameters. Description mentions 'stable ID' as concept but does not explain the 'id' or 'language' parameters, leaving their meaning and format unclear. Minimal value added beyond schema.

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

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

Description clearly states the action (re-fetch) and resource (geocoding feature by stable ID), and distinguishes from sibling tools geocode and geocode_reverse by specifying that the ID comes from those results.

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 to refresh or re-localize a previously discovered place', indicating when to use. Implicitly excludes initial geocoding by referencing prior results, but no explicit when-not-to-use or alternative names.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds that it uses MapTiler service, but no additional behavioral traits (e.g., rate limits, return format, error handling) are disclosed 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?

The description is a single sentence with three example queries, efficiently conveying the tool's purpose. No unnecessary words or repetition—every part earns its place.

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

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

Given 5 parameters, 0% schema coverage, and no output schema, the description is incomplete. It fails to explain the 'limit', 'types', and 'language' parameters or the structure of the response. Annotations cover safety but not functional completeness. The description is adequate for a simple reverse geocoding tool but lacks depth to fully inform an agent about all options.

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% (no descriptions for parameters). The description mentions lat and lon implicitly via examples but does not explain the meaning of 'limit', 'types', or 'language' parameters. The examples show usage but lack semantic detail, leaving agents to infer parameter purposes from names alone.

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

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

The description clearly states the tool converts coordinates to address/locality/region, using natural language examples ('What address is at [lat,lng]'). It distinguishes from sibling 'geocode' (forward geocoding) and other tools like 'coordinates_convert' and 'elevation'.

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 through example queries (natural language, explicit 'reverse geocode'). It doesn't explicitly state when not to use this tool versus alternatives, but the sibling list includes 'geocode' for forward geocoding, implying the distinction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat safety. It adds value by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of listing only active subscriptions. 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 two sentences, front-loading the core action and return fields in the first sentence, and adding usage guidance concisely in the second. 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?

For a simple list tool with one optional parameter and no output schema, the description covers the main purpose, the scope ('caller's subscriptions'), the return fields, and two concrete use cases. No obvious gaps exist given the tool's simplicity.

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

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

The single optional parameter 'include_inactive' is fully described in the schema (100% coverage). The description does not add any extra meaning beyond what the schema provides, so a 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 verb 'List' and the resource 'the caller's active subscriptions', making the tool's purpose unambiguous. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. While it doesn't explicitly state when not to use it, the guidance is clear and actionable, linking to sibling tools implicitly.

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 hints and provide no behavioral safety information. The description compensates fully by revealing key behaviors: 'Filing without an account returns a claim_token', 'pass it back later... to read whether it was fixed', 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' These are substantial behavioral details beyond the annotations, with no contradiction.

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, scope exclusion, content guidance, token mechanics, rate limits, and quota note. It is front-loaded with the core purpose and proceeds through practical details without filler, making it optimally concise for its informational load.

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

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

With no output schema, the description explains return behavior (claim_token) and follow-up workflow. It also covers operational context: team reads digests daily, signal affects roadmap, rate limits, and non-quota usage. Combined with the rich schema and annotations, the description is fully complete for an agent to select and invoke this tool correctly.

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

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

Schema descriptions cover 100% of parameters (baseline 3), and the description adds extra semantic guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' clarifies the message/context parameters, and the claim_token usage is demonstrated with a concrete call example: pipeworx_feedback({claim_token:"pwfb_…"}). This goes beyond the schema's already-strong descriptions, warranting a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from the long list of research/data sibling tools (ask_pipeworx, discover_tools, geocode, etc.), making its purpose unmistakable.

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

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

The description explicitly states when to use it: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage 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, read-only, idempotent behavior. The description adds useful context: caching window (5min-1h), data source (CF analytics), no PII, and self-aggregating nature. This enriches understanding beyond annotations without contradiction.

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

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

The description is concise with three short paragraphs: core function, use-case bullets, and technical details. It is front-loaded and every sentence adds value. No redundancy or filler.

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

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

For a read-only trend tool with simple input and rich annotations, the description covers purpose, use cases, caching, and data source. However, it lacks a detailed output format specification (e.g., structure of returned objects), which would aid agents in parsing results. Still, it provides enough for basic 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% and provides enum values with descriptions. The tool description adds extra context about window behavior (shorter for hot, longer for steady-state), which enhances meaning beyond the schema. This justifies a score above the baseline of 3.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for a given window. It distinguishes itself from sibling tools like discover_tools by focusing on what other agents are calling, not general discovery. The verb 'returns' and specific resource make 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?

Three explicit use cases are given (discovering hot data sources, confirming canonical choice, seeing alignment). No exclusions or alternatives are mentioned, but the context is clear enough that an agent can infer when to use it. Lacks explicit when-not-to-use guidance.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds critical behavioral details: how each mode works, semantic anchor for cross-event, partition filter, output structure, and fill check logic. 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 thorough but somewhat dense; however, every sentence adds value. It is front-loaded with the main purpose and organized with clear sections for each mode and additional checks.

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, including fields like gap_pp, suggested_trade, reasoning, partition_check, and fill check results. It covers edge cases like placeholders and low similarity.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning: examples of event slugs and topic seeds, explains that full URLs are accepted for event, and describes the effect of each parameter in detail.

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 uses a specific verb and resource, and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

The description explicitly explains when to use each mode: no args for trending scan, 'event' for specific market, 'topic' for cross-event scanning. It recommends 'event' for specific markets and provides usage examples. It also warns against trading when fill check shows non-realizable edge, and references 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?

The description goes far beyond the readOnlyHint/idempotentHint annotations, detailing three model families with formulas, caching (1h KV-level), diagnostics for empty segments, and edge calculation specifics (net of slippage, Kelly fractions, 24h-move warning). 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 comprehensive but verbose, with dense technical jargon and some repetition (Kelly explained twice). It is front-loaded with purpose and well-structured, but could be more concise without losing essential information.

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

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

Given 9 parameters, no output schema, and complex nested return structure, the description covers everything: response segments, diagnostics, caching, and parameter behavior. It is complete enough for an agent to understand what the tool does and interpret results.

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

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

Schema coverage is 100% with well-described parameters. The description adds context on how knobs interact (e.g., min_kelly vs min_partition_leg_kelly) and their purpose ('tradeable-edge filters'), but does not significantly enrich individual parameter semantics beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'top Polymarket markets', and is built for 'what should I bet on today'. While it doesn't explicitly distinguish from sibling tools like polymarket_arbitrage, the detailed breakdown of three opportunity segments gives it a unique identity.

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

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

The description provides clear context for usage ('agents discover opportunities without paging hundreds of markets') and explains when to adjust knobs like min_liquidity and max_spread_pp. However, it lacks explicit 'when not to use' or direct comparisons to sibling tools, though the detail on tradeable-edge filters compensates.

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 non-destructive behavior. The description goes far beyond by detailing data sources (daily snapshots), gaps, decay calculation method (daily closes, not intraday), output structure, and limits. 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 information-dense. It front-loads the purpose, then clearly describes response fields and limits. Every sentence adds value; however, it could be better structured with bullet points or sections for readability.

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

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

Despite the absence of an output schema, the description fully compensates by detailing the response structure: tracked[], expired[], snapshot_dates[], including field meanings and edge cases. It also covers limitations (TTL, gap behavior). The tool is a read-only data retrieval tool, and the description provides everything needed 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?

Schema coverage is 100% and includes descriptions. The description adds value by specifying defaults (14 days, '1wk'), clamp ranges (days 2-30), and clarifying the 'window' parameter as 'snapshot family.' This provides additional context beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes from sibling tools like polymarket_edges by focusing on temporal analysis.

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 strong contextual guidance on when to use the tool (e.g., differentiating fresh vs. old edges) and explains key constraints like snapshot gaps and TTL. However, it does not explicitly list alternatives or specify when NOT to use this tool, leaving some ambiguity.

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 (readOnlyHint=true) and no destructive action. Description reinforces this by explaining it is a check that 'walks the ladder' and returns metrics without modifying state. No contradictions.

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

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

The description is relatively long but well-structured with clear sections for single-market and basket modes. Every sentence adds essential information, though slightly verbose for a quick scan.

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 two modes and no output schema, the description thoroughly explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and key warnings (thin_legs, forced_directional_risk). It leaves no critical gaps.

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

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

Input schema has 100% description coverage, but the description adds valuable context beyond defaults and parameter meanings, such as 'max spend on buys, target proceeds on sells' for size_usd and 'auto from partition sum' for side in basket mode.

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

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

The description clearly specifies the tool's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It explains two distinct modes (single-market and basket) and lists the returned metrics.

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 directs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains the rationale (theoretical overround on thin books not capturable, partial fills create directional risk).

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

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

Beyond annotations (readOnlyHint, etc.), the description adds rich behavioral details: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explicit warnings that pre-mapped topics often return warnings. This significantly aids agent understanding.

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

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

The description is dense and well-structured, front-loading the main purpose and then detailing modes, response, and safety fields. Every sentence adds value, 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 no output schema, the description thoroughly explains the response structure and key fields. It covers all essential aspects: modes, safety fields, temporal alignment, and compatibility warnings. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context on how parameters interact (topic vs explicit override) and lists the topic values, enhancing the schema but not dramatically.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than 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 when to use each, with detailed safety warnings about compatibility. It doesn't explicitly compare to alternatives among siblings, but the context is clear enough for an AI agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail and explains the dual behavior (retrieve vs list). 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 action, no fluff. Efficient 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?

Complete for a simple tool with one optional parameter: covers retrieval, listing, scoping, and pairing. 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 coverage is 100% but description adds functional meaning: omitting key lists all keys. This adds value beyond schema.

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

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

Description clearly states the tool retrieves a value saved via 'remember' or lists all keys when key is omitted. It distinguishes from siblings by naming 'remember' and 'forget' as paired tools.

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

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

Explicitly states when to use: 'look up context stored earlier' without re-deriving. Mentions scoping per identifier. Could be improved by explicitly stating when not to use, but the context is clear.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context such as the ability to mark events read with mark_read, which affects subsequent calls. It also discloses the return fields and that polling is acceptable, extending 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 extremely concise (4 sentences) with the main purpose upfront. Every sentence adds value—return fields, filtering, mark_read behavior, and alternative access method—without superfluous words.

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

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

Given 5 optional parameters, no output schema, and comprehensive annotations, the description covers key aspects: what is returned, how to filter, mark_read semantics, and polling suitability. It is nearly complete; a minor gap is no mention of pagination or handling beyond the limit parameter.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description enhances this with concrete examples (e.g., type 'sec_8k'), clarifies the since parameter format (ISO timestamp), and explains the effect of mark_read. This adds meaningful context beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from a subscription feed and specifies what fields are returned (source, citation_uri, raw payload). It also mentions filtering by type and since. However, it does not explicitly differentiate from sibling tools like list_subscriptions or search_within.

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 indicates that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, suggesting a secondary use case. However, it does not provide explicit guidance on when to use this tool versus other alert-related siblings (e.g., subscribe, list_subscriptions).

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

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

Annotations already declare readOnlyHint, destructiveHint false, etc. The description adds details on the fan-out to multiple sources, soft-fail for USPTO, preferred data source order, and output structure.

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 packed with information but well-structured, starting with example queries, then explaining functionality, fallbacks, parameters, and output. 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 tool with 3 required parameters and no output schema, the description sufficiently explains input options and return structure (changes[], total_changes, citation URIs). 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%, but description adds context: examples of valid 'since' values, explanation of 'value' as ticker or CIK, and that 'type' only accepts 'company'.

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 a change feed for a company over a given period, with example queries. It distinguishes from sibling tool entity_profile by specifying different use cases.

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

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

Explicitly provides when to use this tool vs entity_profile: 'Use entity_profile instead when you want the static profile'. Also describes fallback logic between GDELT and GNews.

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 key-value storage scoped by identifier, persistence differences between authenticated and anonymous users (24 hours). Adds value beyond annotations, which only indicate idempotent and non-destructive. 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?

Four sentences, front-loaded with purpose, no redundant information, efficient and clear.

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 key-value store with two parameters and no output schema, the description covers purpose, usage, behavior, and pairing. Complete and sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description provides example keys in schema but does not add new meaning 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 the tool saves data for reuse later. Specific verb 'save' and resource 'data'. Distinguishes from sibling tools 'recall' and 'forget' by mentioning pairing with 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?

Explicitly states when to use: 'when you discover something worth carrying forward'. No explicit when-not, but context implies it's for important information. Mentions pairing with recall and forget for lifecycle.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses rich behavioral details: it returns identifiers labeled by source, explicitly states unresolved identifiers, handles ISIN-to-LEI mapping, and degrades gracefully if GLEIF/OpenFIGI are unavailable. It also notes the internal cascade replaces 2-3 manual lookups.

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

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

The description is long but well-structured with SUPPORTED TYPES and front-loaded examples. It contains some redundancy (e.g., enumerating query paraphrases), but the density of useful information justifies its length. It could be slightly tighter.

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

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

For a tool with no output schema, the description is exceptionally complete: it covers input formats, output identifiers, source provenance, failure behavior (unresolved), degradation, and internal mechanics. This leaves little ambiguity for an agent.

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

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

Although schema coverage is 100%, the description greatly enhances parameter semantics by explaining each type's behavior, providing concrete examples (ticker, CIK, brand/generic), and clarifying edge cases like ISIN inputs resolving to legal entities. This goes far beyond the schema's minimal field descriptions.

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

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

The description opens with concrete example queries and states the core function: resolve a user-spoken NAME to the canonical/official identifiers. It distinguishes from sibling tools by emphasizing that other tools require these IDs, positioning it as the entry point for name-to-ID lookups.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving clear contextual guidance. It also lists supported types, but does not explicitly state when not to use the tool or name alternative tools, so it falls short of a full 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 readOnlyHint, idempotentHint, and non-destructiveHint. The description adds behavioral details: probes each entity, ranks by score, and returns a ranked list with score, confidence, signal density. No contradiction.

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

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

Three sentences: first states main action, second details process, third gives use case and output. Each sentence is valuable and front-loaded. 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, the description explains return format (ranked list with metrics). Parameters are fully covered in schema. The description covers purpose, process, and use case. Could mention entity count limits, but overall adequate.

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

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

Schema coverage is 100%, so parameters are fully described. The description adds high-level context (e.g., first entity is 'subject') but does not provide additional semantic details 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks results, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic) by focusing specifically on AI presence and ranking.

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 gives clear context and an explicit use case ('competitive AI-marketing audits') with an example question. However, it does not explicitly state when not to use or mention alternative tools like ai_visibility_check for single-entity queries.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details fan-out to two services, bundlephobia timing (5-30s), graceful degradation, and sources_failed reporting. 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 and informative, but somewhat verbose. Could be tightened without losing clarity. Front-loaded with purpose and usage.

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

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

Given no output schema, description fully explains return content (summary fields, advisories, links, versions) and edge cases (timeout, partial failure). Covers all necessary context.

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

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

Schema coverage is 100%, but description adds value: for 'package' it notes scoped packages are accepted; for 'version' it states default to latest. Slightly more detail would be ideal, but sufficient.

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

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

The description clearly states 'Composite "should I add this npm package to my project" check in ONE call' and specifies it scans across deps.dev and bundlephobia, distinguishing it from sibling tools like scan_competitor_ai_presence or geocode.

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 guides when to use: 'Use whenever an agent asks "is X safe / popular / small"' and when not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Also mentions partial failures and timing.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag. 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 three sentences, each earning its place: first sentence states the core action, second explains when and why to use it, third adds technical details. No wasted words, front-loaded with purpose.

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

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

For a tool with 3 parameters, no output schema, and comprehensive annotations, the description fully covers behavioral details, use cases, technical constraints, and pairing suggestions. It is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying the max input length (~200K chars) for 'text', natural-language query examples for 'query', and the default and range for 'limit'.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K body or article. It distinguishes itself by explaining it returns passages with character offsets and similarity scores, which is unique among siblings.

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

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

The description explicitly tells when to use: when the record is too big for the prompt. It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly list alternatives or when not to use, slightly lowering the score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that the tool returns a fetchable PNG URL and requires no interactive JS, which is consistent with annotations. It does not contradict annotations. The behavioral transparency is adequate given the annotation coverage.

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, with a single sentence that front-loads common usage patterns. Every phrase adds value, and there is no redundancy. The structure is efficient and easy to parse.

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

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

Despite lacking an output schema, the description states that the tool returns a 'fetchable PNG URL', which is sufficient for understanding the return value. It covers the main inputs and outputs. The tool is simple, and the description provides enough context for correct usage, though it could mention that the URL is directly 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 0%, so the description must compensate. It mentions 'style + coords + zoom + width/height' but does not elaborate on each parameter (e.g., marker, retina, attribution). The examples in the schema provide some context, but the description itself lacks detailed parameter semantics. This is a moderate compensation.

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: returns a MapTiler static-tile image URL for embedding. It uses specific verbs and resources ('returns a MapTiler static-tile image URL') and provides example use cases ('embed a map', 'map thumbnail', 'screenshot of map'). While sibling tools like 'tiles_json' might be related, the description sets it apart by focusing on static image URLs for embedding.

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 clear usage patterns ('embed a map', 'map thumbnail PNG', 'screenshot of map') but does not explicitly state when to avoid using this tool or mention alternatives like 'tiles_json' for interactive maps. It implies usage for static embedding scenarios, which is helpful but lacks exclusion criteria.

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

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

Annotations indicate idempotent, non-destructive, non-readonly. Description adds: requires OAuth, returns subscription id, SMS cap (10/day), webhook auto-disable after 10 failures, verification step for SMS. 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?

Well-structured: purpose first, then prerequisites, then type options, then delivery channels. Length is justified—every sentence adds value. Slightly verbose but efficient for a complex tool.

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?

Complex tool with multiple types and delivery options; description covers prerequisites, type-specific params, delivery behaviors, limits, and return value. No output schema but declares subscription id return. Complete for agent selection and invocation.

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

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

Schema coverage 100%, baseline 3. Description adds type-specific examples, delivery channel details (webhook signing, SMS verification, email). Significantly enriches param meaning.

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

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

Clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' Returns subscription id. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisite (Pipeworx OAuth account) and alternatives for each type and delivery channel. Implicitly not for one-off lookups—use siblings. Lacks explicit when-not-to-use but offers strong contextual 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 readOnly, openWorld, idempotent hints. Description adds valuable context: returns live catalog examples with tool+argument shapes, type of categories, and that it's drawn from thousands of tools. 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 thorough but somewhat lengthy. It is well-structured with a front-loaded purpose and detailed breakdown, though some repetitions could be trimmed. Still effective.

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

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

Given the tool's simple onboarding purpose, all necessary information is present: purpose, usage, parameter details, and what the response looks like. No output schema but description covers return format adequately.

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

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

Schema coverage is 100% with a description for the topic parameter. The description adds more detail (list of topic values and the behavior when omitted), enhancing the schema info.

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

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

The description clearly defines the tool as an onboarding entry point for Pipeworx, explaining it returns category-bucketed example questions. It distinguishes from siblings by noting it should be used first to learn what Pipeworx can do, with references to meta-tools like ask_pipeworx.

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 ('FIRST when you do not yet know what Pipeworx can do'), provides examples of queries, and outlines how to customize with optional topic parameter. Mentions alternatives indirectly via reference to meta-tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds context about returning TileJSON spec metadata but does not disclose additional behaviors such as rate limits, authentication requirements, or the full response format. Given the strong annotation coverage, a score of 3 is appropriate.

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 consists of two concise sentences. The first sentence defines the tool's output, and the second provides usage guidance. Every sentence serves a clear purpose with no redundancy or filler. It is front-loaded with the core function.

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 (single parameter, extensive annotations, no output schema) and its niche audience (GIS integrators), the description covers the essential context: what the tool returns and when to use it. It could be improved by describing the 'tileset' parameter or the TileJSON schema, but the specialist audience may already know this. The example in the schema partially compensates.

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

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

The input schema has only one parameter ('tileset') with 0% description coverage. The description mentions 'MapTiler tileset' but does not explain what valid values are, how to specify them, or any constraints (e.g., it only shows 'openstreetmap' in the example). With no schema description and minimal description guidance, the agent may struggle to invoke the tool correctly.

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 precisely states the tool returns TileJSON spec metadata (zoom range, bounds, layer schema) for a MapTiler tileset. It explicitly distinguishes the tool as a specialist tool for GIS integrators, contrasting with geocode/static_map_url for general users. This clearly communicates the tool's purpose and differentiates it from siblings like geocode and static_map_url.

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 guidance: use this tool when you need TileJSON metadata for GIS integration. It also advises that most users should use geocode/static_map_url instead, effectively telling the agent when not to use this tool. While it doesn't explicitly name other sibling tools for GIS tasks, the guidance is sufficient for decision-making.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Annotations already indicate non-destructive and idempotent; description adds valuable detail beyond annotations.

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

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

Two sentences, zero waste. Action is front-loaded and each sentence adds essential information.

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

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

For a simple tool with one parameter, good annotations, and no output schema, the description fully covers the behavioral and usage context 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 coverage is 100% with a clear description of the id parameter. Description does not add new semantic information beyond the schema, 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 'Cancel a subscription by id' and the resource 'subscription'. It distinguishes itself from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Does not explicitly state when not to use but implies it.

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

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

While annotations already indicate read-only/idempotent/non-destructive, the description adds rich behavioral context: routing logic, verdict set, citation output, and crucial warnings about 'could_not_verify' (carries verification_error, not evidence) and 'unsupported' (no source coverage). This goes well beyond the annotation hints and significantly helps the agent interpret results correctly.

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 every sentence carries value: trigger phrases, usage directive, routing logic, return values, and a clear caller warning are all front-loaded. It is well-structured with an 'IMPORTANT for callers' note. A slight deduction for verbosity—it could be tightened without losing substance—but it is not padded.

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

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

With no output schema, the description fully compensates by listing all possible verdicts, explaining the verification_error field, and distinguishing 'could_not_verify' from 'unsupported'. It also covers both claim categories and the fallback pipeline. This is complete for a tool with 2 params and no output schema.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful extra-parameter semantics: it explains that tolerance_pct defaults to the implication of the claim wording, is capped at 5, and recommends setting 1-2 for hallucination detection. This practical guidance exceeds 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 the tool performs 'natural-language claim verification against authoritative sources' and lists concrete trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…'). It distinguishes from siblings by describing two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for all others), making the purpose unambiguous and differentiated.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger examples. It also explains when the financial fast path applies versus the general pipeline. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusionary guidance.

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