SeaWeb

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

The description adds meaningful behavioral context beyond the readOnly/idempotent annotations: it is an authenticated caller-owned lookup, and missing versus wrong-owner job IDs return identical 404 responses. This alerts the agent to privacy-conscious error design. 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?

Three short sentences, front-loaded with the core purpose, followed by essential ownership and error-behavior caveats. Every sentence adds value and there is no redundancy.

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

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

For a single-parameter read-only tool with an output schema and safety annotations, the description covers purpose, ownership model, and a critical error-handling nuance. The only minor gap is not stating how to obtain the job_id, but this is somewhat inferable from the async job creation context and sibling tools.

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

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

Schema coverage is 0% and the description does not explain what a job_id looks like, where it comes from, or any format constraints. It only references job IDs in the context of missing/wrong-owner 404s, which is useful but insufficient for a parameter with no schema-level documentation.

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 names a specific operation ('Check status'), a clear resource ('asynchronous STORM or Dataset agent job'), and scopes the lookup to caller-owned jobs. This distinguishes it from generic status tools and related siblings like cancel_agent_job and research_status.

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

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

The description implies the tool is for polling or checking asynchronous agent jobs and notes ownership restrictions, but it does not explicitly say when to prefer this over the sibling research_status or how it relates to cancel_agent_job. The 404 behavior gives useful context for handling responses, but the when-to-use guidance is only implicit.

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 only sparse annotations (readOnlyHint false, idempotentHint false, destructiveHint false), the description carries most of the behavioral burden. It usefully discloses that the tool creates an isolated Postgres agent job and that results are strictly grounded with exact evidence text and character slice offsets. It does not explain how to monitor or retrieve the job, but the added behavioral context is meaningful.

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 compact and well-structured: a one-line purpose statement followed by three short clauses covering inputs, job creation, and grounding guarantees. Every sentence earns its place, with no redundant restatement of schema fields.

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 an asynchronous dataset-building tool with an output schema present, the description covers the core inputs, isolation, and grounding guarantee. However, it omits limit semantics, the flexible columns input format, and an explicit pointer to agent_job_status for checking the created job, which an agent would need to use it end-to-end.

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 maps query to 'task/topic query' and columns to 'requested column names', which adds some meaning. However, it says nothing about the limit parameter and does not explain that columns can be a string, array, or null, leaving partial parameter 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 opens with a concrete verb ('Build') and a specific deliverable ('grounded structured dataset grid from web extraction'), then clarifies inputs and job creation. It is clearly distinguishable from generic search or recall tools, though it does not explicitly name or contrast a sibling tool, so it falls short of a 5.

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 communicates a clear use context: turning a task/topic query and requested columns into a web-extracted, grounded dataset. It does not explicitly state when not to use it or name alternatives like research, search_web, or extract_url, but the context is strong enough that an agent can infer the intended scenario.

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 carry destructiveHint and idempotentHint; the description reinforces idempotency and adds that the operation is 'Authenticated, owner-scoped,' which is useful safety context. It doesn't detail failure behavior, but the annotations plus output schema cover the main safety traits.

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 compact lines, front-loaded with the action and target; the trailing 'Authenticated, owner-scoped, idempotent' adds safety-relevant facts without fluff.

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

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

For a single-parameter destructive action, the description is nearly complete: it covers target, state, authentication scope, and idempotency, and an output schema exists so return values don't need to be described. The main omission is source of job_id, but that's minor for this 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?

Only parameter is job_id; the description doesn't explicitly document it, and schema coverage is 0%. The phrase 'STORM or Dataset agent job' gives some context that job_id is the identifier of such a job, but doesn't say how to obtain it or validate it, so compensation for the low coverage is partial.

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

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

Description uses a specific verb ('Cancel') and identifies the exact target: 'queued or running STORM or Dataset agent job.' This clearly differentiates it from status/research siblings like agent_job_status and research_status.

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 context on when to call it — for queued/running STORM or Dataset jobs — and the owner-scoped note implies only the owning user should invoke it. It doesn't name an alternative, but there is no other cancel-job sibling, so the routing is unambiguous.

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 a safe read-only, idempotent operation. The description adds substantial behavioral context: it ranks the same query under two rankers, returns a pre-formatted two-column table, and mandates a specific follow-up workflow including showing output verbatim, submitting an agent verdict, and recording the human verdict.

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?

Every sentence carries necessary information, starting with purpose and usage, then behavior, then required follow-up actions. Despite the density, there is no filler and the structure is logical.

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

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

The operational workflow and output expectations are well covered, and the output schema relieves the description of explaining return values. However, the tool cannot be reliably invoked because the three input parameters are entirely undocumented in both the schema and the description, creating a clear completeness 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 description coverage is 0%, so the description must compensate, but it never explains the 'intent', 'track_b', or 'location' parameters. It refers to 'same query' without explicitly mapping that to the intent parameter, and gives no guidance on what values track_b or location should take.

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 names a specific operation: A/B ranking comparison between the served ranker and a challenger. It clearly distinguishes this from normal search and from vote_comparison, which is described as a follow-up step rather than the same tool.

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

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

The description explicitly states when to use the tool: after a normal search session when the human wants to judge result quality. It also implies a temporal exclusion by requiring a prior search session, but it does not explicitly name alternatives or conditions when this tool should not be used.

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 idempotentHint and destructiveHint annotations, it discloses exact idempotent behavior (unknown/already-deleted/not-yours returns deleted=false instead of an error), the return shape, the authentication requirement, and the unusual policy that deletion stays open for lapsed accounts. This is significant value added over 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 first paragraph is tight and front-loaded with purpose, ownership, idempotency, return shape, and auth. The second paragraph's long historical rationale is valuable context but verbose and could be trimmed without losing critical 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?

For a destructive tool with no output schema and sparse parameter docs, the description provides enough to call it correctly: required credentials, tenant namespace, idempotent failure behavior, and the response payload. Nothing essential is missing.

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

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

Schema coverage is 0%, but the description compensates by explaining that tenant_id is the ownership namespace from registration and that subscription_id identifies the webhook to delete. It does not fully describe how to obtain subscription_id or the effect of omitting/leaving tenant_id null, which prevents a 5.

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

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

States a precise action: delete ONE webhook subscription the caller registered, with explicit ownership scope. This clearly differentiates it from register_disruption_webhook and list_disruption_webhooks 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 gives clear calling context: pass the same tenant_id used at registration and provide an authenticated key. It does not explicitly name alternatives such as delete_standing_query or tell the agent to list webhooks to find the subscription_id, so it falls short of a full when-not-to-use statement.

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

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

The description goes well beyond the annotations. While idempotentHint=true and destructiveHint=true are already present, the description explains the exact idempotent behavior: unknown, already-deleted, or not-yours ids return deleted=false rather than an error. It also discloses the authenticated-key requirement and the ownership/tenant namespace nuance, which are not visible in the annotations or schema.

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 yet well-structured. Every sentence adds operational value: scope, ownership, idempotency, return shape, and authentication. The main purpose is front-loaded, and there is no filler or repetition beyond what is needed for 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?

For a destructive, idempotent mutation tool with no output schema, the description provides all essential context: ownership rules, tenant namespace requirements, idempotent result behavior, expected return shape, and authentication needs. Nothing critical is missing for an agent to 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 description coverage is 0%, so the description carries the full burden for parameter meaning. It explains that query_id identifies the standing query and gives substantial semantic detail for tenant_id, including the requirement to pass the same tenant_id used at registration and the sub-label ownership implication. It does not specify the exact format of query_id, but the operational meaning is clear.

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

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

The description states a specific verb ('delete'), a specific resource ('one of YOUR standing disruption queries'), and the identifying key ('by query_id'). It clearly distinguishes this from sibling tools like delete_disruption_webhook and list_standing_queries by focusing on deletion of a standing query owned by the caller.

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 clearly communicates when this tool is appropriate: delete only queries registered by the calling account, and pass the same tenant_id used during registration. It provides important exclusions ('only queries registered by the calling account can be deleted') but does not explicitly name sibling alternatives or state when not to use this tool in favor of another.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, but the description goes well beyond them: it discloses noindex refusal, nosnippet behavior, untrusted_content always true, raw_bytes vs text_bytes, cache_hit, stale, age_seconds, error cases, and the exact passage-shape changes per extract_mode. This is exemplary transparency for a read-only fetch tool.

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

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

The description is well-organized and front-loaded with the core one-liner, and the dense later sections add real value. However, extract_mode behavior is explained twice—once in the bullet list and again in a paragraph—and the opt-in note repeats parts of the breaking-change rationale. This redundancy costs a point but is tolerable for an unusually 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?

With no output schema and only minimally descriptive parameter names, the description covers nearly every fact an agent needs: return keys, source behavior, error conditions, offset semantics, subset guarantees, backward compatibility, and sample reconstruction code. There is no material gap in context for selecting or invoking 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 description coverage is 0%, so the description must carry all parameter semantics, and it does. It explains the url as the single required input, format values (json, markdown, and fallback behavior for any other value), and extract_mode values (legacy, spans/readable, raw) with their defaults and output shapes. No parameter is left to guesswork.

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 crisp formula—'One URL in, that page's clean readable content out'—and names the exact return fields (title, text, passages, source). It further distinguishes the tool from search_web by stating search_web finds pages while this reads one you already have, removing any ambiguity about what the tool does.

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 contrasts the tool with search_web ('search_web finds pages; this reads one you already have'), telling an agent when to choose it over the obvious sibling. It also gives nuanced usage guidance for index vs live sources, how markdown mode affects output, and when to use extract_mode variants, making the invocation conditions 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 establish read-only and idempotent behavior. The description adds the scoping detail that this operates on the registry or prior search hits, which is useful, but it does not explain how criteria combine or what the response contains, partly mitigated by an output schema.

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 definition is a single sentence with no filler, and the key operating concept is front-loaded. The 'structured /grep' phrasing is somewhat jargon-heavy but does not waste space.

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 7-parameter tool with no parameter descriptions, this one-liner is too thin. It does not explain what 'registry' means, how to chain it with search results, how criteria interact, or what values the filter fields accept. The read-only annotations and output schema reduce the risk, but correct invocation still relies heavily on guessing.

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

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

Schema description coverage is 0% and the description compensates only marginally. 'Subset of prior search hits' hints at restaurant_ids, but the other six parameters are left to their names, with no value formats or allowed semantics specified.

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 says this is a 'structured /grep filter' and names its operating scope: 'registry or subset of prior search hits.' Combined with the tool name and annotation title 'Filter restaurants,' an agent can tell it filters existing restaurant data rather than searching broadly, though the exact meaning of 'registry' is left 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?

It gives a clear usage context: apply this when you need to filter the full registry or already-obtained search results. It does not explicitly name alternatives like search_restaurants or state when not to use them, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: it operates on a closed registry or a prior hit subset, behaves like a structured grep filter, and is salon-only. These go beyond the structured annotations and align with openWorldHint=false.

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?

One dense, front-loaded sentence with no filler. It communicates operation, resource, data source, and vertical scope without redundancy.

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

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

For a closed-world, read-only filter with an output schema, the description covers the essential invocation context: what is filtered, from where, and over which vertical. Some per-parameter detail is missing, but the overall behavior is sufficiently complete given the annotations and output schema.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only clarifies salon_ids as a subset selector for prior search_salons hits. The other five parameters (price_range, neighborhood, open_tonight, publisher_id, accepts_reservations) receive no additional explanation beyond their names, leaving value/format ambiguities unresolved.

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 names a specific operation ('Structured /grep filter') on a specific resource ('salons'), and immediately scopes it to either the registry or a subset of prior search_salons hits. 'Salon-only vertical' clearly distinguishes it from sibling filter_restaurants and search_salons.

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

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

The description provides clear context: use this to filter the salon registry or to refine a prior search_salons result set via salon_ids. It does not name alternatives explicitly or state when not to use it, but the vertical scoping and reference to prior search_salons hits give practical guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing the 30-minute update interval, the 2-hour verdict freshness window, the rule that stale rows 'never speak for the group', indeterminate-read exclusion semantics, the exact meaning of 'verdict: null', and the empty-cameras-list edge case. It never contradicts the annotations, which all align with a read-only, idempotent operation.

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 dense paragraphs with the purpose front-loaded and every sentence earning its place: field names, value ranges, null semantics, staleness rules, and edge cases. Because there is no output schema, the length is justified — it substitutes for structured return documentation rather than padding.

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 and nested return data, the description thoroughly documents the response shape (vision fields, history, hourly averages, verdict), critical null semantics, freshness behavior, and edge cases. The only notable gap is the undocumented 'limit' parameter, plus 'trip-planning stats' is named but not elaborated beyond the hourly averages.

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

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

The single parameter 'limit' has 0% schema description coverage and the description never mentions it — no explanation of what it caps (cameras returned? history points?), its relationship to the row structure, or how it interacts with the verdict. With coverage this low, the description was required to compensate, and it does not.

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?

States a specific resource ('Landmark camera visibility'), the data source ('vision-model readings of public webcams... Golden Gate Bridge Caltrans set'), and the delivered artifacts (per-camera history and trip-planning stats). The opening sentence clearly differentiates this from generic weather or condition lookups by anchoring it to webcam vision readings.

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 'honesty labels' section gives strong contextual guidance about what the data is and is not — 'not an NWS station, not a forecast' — which tells an agent when this tool's output can and cannot be trusted. It stops short of naming sibling alternatives or explicit when-to-use/when-not-to-use conditions, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the result is a menu/service list slice, but it doesn't disclose additional behavioral details such as error cases, data availability, or response 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 a single focused sentence that front-loads the core behavior and includes a useful sibling comparison. Every word contributes, with no filler or repetition of schema details.

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

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

Given the low complexity of the tool, strong annotations, and a single required parameter, the description is largely sufficient. It communicates the return category ('menu / service list') and the vertical-agnostic scope, though a bit more detail about the expected entity_id usage would make it fully complete.

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

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

Schema description coverage is 0%, and the description does not explain entity_id beyond the phrase 'for one entity,' which largely restates the parameter name. The parameter is self-evident to some degree, but the description fails to provide any additional meaning such as how to obtain entity_id or expected value formats.

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

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

The description clearly states that this tool returns a detail slice for one entity, specifically a menu or service list. It also distinguishes itself by calling out get_menu/get_services as vertical-specific siblings, making its unique role immediately clear.

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 names the alternative tools and characterizes get_details as the 'vertical-agnostic counterpart' of get_menu/get_services, which gives the agent strong contextual guidance. It doesn't explicitly state when not to use it, but the counterpart relationship implies the selection criterion well.

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, and non-destructive behavior. The description adds a valuable behavioral guarantee: the returned event and its source set are frozen as of emission and later evidence never mutates it. This is exactly the kind of state semantics an agent needs to trust the result.

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?

One concise sentence front-loads the verb, resource, and lookup key, then adds a compact parenthetical explaining immutability. 'Travel Product B' is minor context but does not bloat the description.

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?

There is no output schema, but the description still conveys what the response contains: the disruption event plus its frozen source set as it stood at emission. For a simple read-by-ID tool, this is complete and gives the agent the critical semantic 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 has one parameter with 0% description coverage, but the description explicitly ties event_id to selecting which disruption event to fetch. It does not specify where the ID comes from or its format, but for a single simple string parameter this is 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?

States a specific verb ('fetch'), a specific resource ('one disruption event'), and the lookup key (event_id). It also distinguishes itself from sibling list tools like list_disruption_events by emphasizing singular retrieval and the frozen, span-grounded source set.

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?

Clear context: use this tool when you need a single disruption event identified by event_id, especially when evidence-at-emission semantics matter. It does not explicitly name alternatives or exclusions, but the singular-by-ID framing makes the intended use obvious relative to listing tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: live poller, partial and US-only feed coverage, country-level advisory limits, empty-result semantics, and `freshness`/`join_eligible` labels. There is 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?

Purpose and key caveats are front-loaded in the first paragraphs, and later source bullets are verbose but mostly justified by the data-coverage complexity. The length is high but each section contributes to avoiding misinterpretation of results.

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

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

Covers source coverage, filtering behavior, country-level caveats, empty-result meaning, and honesty labels, while the output schema handles return-shape details. The only material omission is the meaning of `limit` and `query`, so it is nearly complete rather than fully complete.

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

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

The description richly explains lat/lng and ugc semantics, adding real meaning beyond the bare schema titles. However, `limit` and `query` are never mentioned, and with 0% schema description coverage the description is the only documentation for them. This compensation is incomplete.

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?

Opens with 'active disruption alerts (weather, safety, travel advisories) for a region', clearly stating a specific verb, resource, and scope. It also differentiates itself from the sibling `list_disruption_events` by describing this as the unfiltered surface and pointing to that tool for richer filtering.

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 details when to use lat/lng versus `ugc`, and says to omit all filters to get every active alert including advisories. It names `list_disruption_events` as the richer filtered alternative, so an agent has concrete selection 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, so the safety profile is covered. The description adds useful context about returning a full schema.org page and accepting multiple identifier forms, but does not disclose any additional behavioral details like not-found handling or response size.

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

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

The description is one efficient sentence, front-loaded with the core purpose ('Full schema.org page for one entity') and immediately followed by the accepted identifier forms. There is no filler or repetition of structural schema 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 single-parameter, read-only tool with no output schema, this description is largely complete: it explains what the tool returns and how to identify the entity. The remaining gap is the lack of explicit routing among the many get_* sibling tools, but that is a minor omission given the simple contract.

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 provides only a bare entity_id string with 0% description coverage. The description fully compensates by defining the canonical id syntax (seaweb://{vertical}/{slug}), confirming legacy ids are accepted, and clarifying that a unique bare slug also works. This is strong parameter guidance for a single-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 a specific verb and resource: it returns the full schema.org page for one entity. It also specifies the accepted identifier forms. It does not explicitly name or differentiate from overlapping siblings like get_details, so it stops short of a 5.

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

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

The description implies when to use the tool: when you have a canonical id, legacy id, or unique bare slug and want the full schema.org page. However, it gives no explicit guidance about when not to use it or which sibling tool should be preferred for more specific entity lookups.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds the genuinely useful behavioral trait that restaurant_id and entity_id are aliases and either one is accepted, which is not derivable from annotations and is critical for correct invocation.

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 short sentences with zero wasted words. The purpose is front-loaded in the first sentence, and the second sentence delivers the critical alias clarification. Every word 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?

For a simple two-parameter read tool with no nested objects, this is nearly complete. Annotations cover safety and idempotency, and the description handles the parameter relationship. Minor gaps remain: no output schema means return format, timezone handling, and not-found behavior are unspecified.

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 — and it does by resolving the core ambiguity: the two parameters are aliases. Without this, an agent might pass both or not know they are interchangeable. It doesn't specify ID format, but that is a minor gap given minLength is the only schema constraint.

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

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

The description states a specific verb ('Return') and resource ('opening hours for a restaurant'), making the tool's function unambiguous. It differentiates well from sibling tools like get_restaurant, get_menu, and get_services, which target different resources.

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?

Usage context is implied by the purpose: an agent should call this when it needs opening hours for a restaurant. The alias note ('pass either') provides useful invocation guidance, but there is no explicit when-to-use versus-alternatives statement or exclusion naming siblings like get_restaurant.

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, covering the safety profile. The description adds useful behavioral context: the result is a schema.org Menu structure and the two identifiers are interchangeable aliases. There is no contradiction with 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?

Two short sentences with no filler; the core purpose is front-loaded and the alias note is the only extra needed. Every word 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?

For a simple read-only tool with two parameters, the description covers purpose, return shape, and parameter relationship. The lack of an output schema is partly mitigated by the schema.org Menu reference, though exact menu fields are not enumerated. This is adequately 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 description coverage is 0%, so the description must carry parameter meaning. It does exactly this by stating that restaurant_id and entity_id are aliases and that either may be passed, clarifying the schema's anyOf constraint. It does not describe identifier formats or precedence, but the alias clarification is high-value.

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

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

The description opens with the specific verb 'Return' and the resource 'structured menu for a restaurant,' and even names the output shape as schema.org Menu. It clearly identifies the tool's function, though it does not explicitly contrast it with sibling tools like get_restaurant or get_hours.

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

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

The description implies the tool is for retrieving a restaurant's menu but gives no explicit guidance on when to choose it over siblings such as get_restaurant or get_hours. There is no 'use X instead' statement or exclusion criteria. This is implied usage rather than explicit 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 cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds that the return value is a full schema.org Restaurant page and that the two IDs are aliases, but it does not disclose behavior such as not-found responses or what happens if both IDs are provided. This is adequate but not rich.

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

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

The description is two sentences with no wasted words. The main purpose is front-loaded, and the alias clarification is directly useful. The internal 'E2-A /get slice' reference is slightly opaque but does not detract from conciseness.

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

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

For a simple read-only lookup with strong annotation coverage, the description is nearly complete: it states the return type and parameter alias behavior. It could briefly mention when not to use it or how invalid IDs are handled, but those are minor gaps given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It does so meaningfully by clarifying that restaurant_id and entity_id are aliases and either can be passed, which resolves the central parameter ambiguity. It leaves some details implicit, such as value format and precedence when both are supplied, but the main relationship is made clear.

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

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

The description states a specific verb and resource: 'Return full schema.org Restaurant page.' This clearly identifies what the tool does and distinguishes it from get_salon or get_entity by resource type. It does not explicitly name sibling alternatives, so it falls just short of a 5.

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 invocation guidance ('restaurant_id and entity_id are aliases; pass either') but no guidance on when to use this tool versus siblings like get_entity, get_details, or get_salon. The usage context is only implied by the tool name and 'Restaurant page.'

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 establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations by specifying the return content ('full schema.org page' with 'profile + meta') and explicitly documenting that salon_id and entity_id are interchangeable aliases. No contradiction found.

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 focused sentence followed by a short, essential alias note. Every word earns its place, with the core purpose front-loaded.

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

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

For a simple read-only getter with strong annotations, the description adequately covers the return type and parameter relationship. It is slightly incomplete on usage context relative to sibling tools, but the core calling information is present.

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

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

Schema description coverage is 0%, so the description carries the parameter burden. It clearly explains that salon_id and entity_id are aliases and that either can be passed, which resolves what would otherwise be ambiguity in the input schema. It does not add format details, but the alias clarification is the key semantic needed.

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

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

The description states a specific verb ('Return') and resource ('schema.org page for a salon'), and clarifies the output scope as 'profile + meta'. It is clear what the tool does, though it does not explicitly contrast with sibling tools like get_entity or get_details.

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

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

There is no guidance on when to use this tool versus alternatives such as search_salons, get_entity, or get_details. The alias note helps invocation but not selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing the safety profile. The description adds useful behavioral context beyond annotations: the return shape is a schema.org Menu composed of sections of priced services, and the two parameters are equivalent aliases. There is 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?

Two compact sentences carry all the essential information: purpose, return shape, sibling relationship, and parameter alias behavior. The most important detail is front-loaded, and there is no redundant or filler text.

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

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

For a simple read-only lookup with two string parameters and no output schema, the description provides the return shape, the alias usage, and the sibling distinction. Annotations cover the safety and idempotency expectations. Nothing critical is missing 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 description coverage is 0%, so the description must compensate. It directly clarifies the relationship between salon_id and entity_id, stating they are aliases and either may be passed. This resolves the anyOf ambiguity that the raw schema leaves unexplained. Parameter names and minLength constraints cover the remaining needs for simple string identifiers.

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

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

The description states a specific verb and resource: 'Return a salon's service menu' with the schema.org Menu shape. It also explicitly names get_menu as the counterpart, which distinguishes this tool from a closely related sibling without opening any schema.

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?

'Salon counterpart to get_menu' provides clear guidance on when to use this tool versus the sibling alternative. The alias note 'salon_id and entity_id are aliases; pass either' also removes any ambiguity about which parameter to provide, directly addressing a confusing aspect of the input schema.

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 safety is covered. The description adds useful behavioral context beyond those annotations by disclosing that the returned pack includes allowlisted facts, closure status, server-generated typed actions, and the caller's own past actions with the entity. This helps an agent understand the tool's personalized, consolidated nature.

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 and mostly front-loaded, immediately establishing that the tool is a compact action pack for one entity. The list of included content is dense but relevant, with no filler. The main cost is jargon like 'allowlisted facts' and 'server-generated typed actions', which slightly reduces clarity but not 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?

For a one-parameter, read-only tool, the description provides a reasonable overview and names the categories of returned content. However, with no output schema, it leaves the exact shape and meaning of 'typed actions' and 'allowlisted facts' underspecified. An agent might still need additional context to confidently interpret the response.

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 has one required parameter, entity_id, with 0% description coverage. The description refers to 'ONE entity' and 'this entity' but does not explain what form entity_id should take, how to obtain it, or any constraints. With schema coverage that low, the description needed to compensate and did not.

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 conveys that this tool retrieves a consolidated bundle of information and actions for a single entity, listing specific contents like allowlisted facts, closure status, and past actions. It does not use an explicit verb like 'retrieves' or 'returns', and it does not directly name a sibling to distinguish from, but the resource and scope are clear.

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 phrase 'everything an agent needs to act there without re-reading full pages' implies this is meant for entity-level action contexts. However, it gives no explicit when-to-use or when-not-to-use guidance, nor does it compare itself with closely related siblings such as get_entity or get_details. Usage context is suggested but not fully specified.

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?

Goes well beyond the readOnly/idempotent annotations by explaining the status domain (good|caution|bad|unknown), the verdict rule ('worst non-unknown factor'), the exact meaning of 'unknown' (empty or stale feed, never all-clear), the live-vs-forecast split, and proxy camera caveats. This is substantial behavioral disclosure.

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

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

Front-loaded with a one-line summary, then structured into usable sections covering factors, invocation, status semantics, and edge cases. Every sentence adds operational value rather than repeating schema or annotation information. The length is justified by the absence of an output schema.

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

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

The description is unusually complete for a tool with no output schema: it explains the verdict, statuses, factor sources, forecast-only week rows, live signals in factors, flagged status, unknown handling, and proxy camera notes. It does not specify the exact response envelope or behavior for an invalid/omitted spot_id, which leaves a small 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?

With 0% schema description coverage, the description carries the full burden for spot_id. It provides concrete example values ('golden-gate', 'napa', 'big-sur') and explains that passing one returns that spot plus its weekly outlook. It does not enumerate all valid spot IDs or state what happens if spot_id is omitted, but it gives enough 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?

Clearly states it returns a trip-condition board for tracked tourist spots with one verdict per spot and per-factor readings. The geographic scope and factor list make the purpose concrete and distinguishable from generic weather tools. It does not explicitly contrast with sibling tools like get_camera_visibility or travel_health, so it misses the top score.

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

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

The description implies when to use the tool — trip planning at SF Bay Area, Napa, and Big Sur spots — and mentions 'for picking a visit day'. However, it gives no explicit when-to-use/when-not-to-use guidance or alternatives, leaving the agent to infer selection from context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: events are structured and frozen, severity and confidence ranges are specified, sources are span-grounded, and truncated=true signals pagination limits. 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 dense but every sentence adds operational value: purpose, record structure, filter semantics, polling workflow, and sibling differentiation. It is front-loaded with the core action and product context, and no filler is present.

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?

There is no output schema, yet the description covers record shape, field semantics, filter behavior, pagination, and the intended workflow. An agent has enough context to invoke this tool correctly and interpret its 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 description coverage is 0%, but the description documents all four parameters: since with ISO-8601 and emitted_at comparison semantics, geo_id, disruption_type, and limit with default, max, and truncation behavior. It fully compensates for the schema's lack of parameter 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 states a specific verb ('list') and resource ('emitted disruption events' for Travel Product B), and explicitly distinguishes it from the sibling get_disruptions feed. An agent can immediately understand what this tool does and how it differs from similar 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?

It explicitly tells the agent when to use it: poll after register_standing_query, or inspect recent disruptions ad hoc. It also names the get_disruptions alternative and clarifies that this tool is the corroborated, standing-query travel stream, not the US weather/advisory feed.

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 and idempotent, and the description adds valuable behavioral details beyond that: secrets are NEVER echoed, results are scoped to the calling account, and tenant_id sub-labels are separate namespaces rather than filters. This is exactly the kind of context an agent needs to avoid misuse or misinterpretation.

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

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

The description is front-loaded with the core purpose and the most security-relevant detail (secrets never echoed). It is compact but contains one somewhat extraneous prefix, 'Travel Product B', which adds context but is not essential. Overall, every other 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?

For a simple list operation with one optional parameter and no output schema, the description covers the key bases: what is returned, what is never returned, scoping rules, tenant_id semantics, and the authentication requirement. Nothing critical is missing for an agent to 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 description coverage is 0%, so the description carries the full burden of explaining tenant_id. It does this very well, describing it as an optional sub-label within the caller's own namespace, clarifying that it is not a filter and must match the registration value. This is significantly more informative than the bare 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 states a clear verb and resource: 'list YOUR registered webhook subscriptions'. It further specifies the returned fields (subscription_id, url), making it unmistakably distinct from sibling tools like register_disruption_webhook or delete_disruption_webhook.

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 usage context: it clarifies that the tool is scoped to the calling account and that tenant_id must match the one used during registration. It does not explicitly name alternatives or exclusion conditions, but the listing behavior and tenant_id semantics provide clear guidance for when this tool applies.

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 signal readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds the detail that output includes entity counts and coverage, but does not mention pagination, ordering, or limits; given the annotation coverage, this is adequate but not outstanding.

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

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

A single, front-loaded sentence with no filler. Every phrase ('List', 'indexed publishers', 'with entity counts and coverage') contributes meaning.

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

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

For a no-parameter, read-only list operation with an output schema available, the description covers the essential information an agent needs: what is being listed and what the result includes. There are no missing prerequisites or configuration details.

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

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

The tool takes zero parameters, and schema description coverage is trivially 100% since the schema is empty. The description does not need to explain parameters, so the 0-param baseline of 4 applies.

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

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

The description states the specific verb 'List' and resource 'indexed publishers', and enriches it with 'entity counts and coverage'. This clearly distinguishes the tool from sibling list tools like list_standing_queries or list_verticals, which target different resources.

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

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

The description implies usage when an agent needs an overview of indexed publishers, and the read-only annotations make it safe to invoke. However, it offers no explicit guidance on when to prefer it over sibling list tools or any context about alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds meaningful context beyond them: authentication is required, results are scoped to the calling account, and each entry is the stored containment-expanded query as it percolates against documents. This gives the agent concrete expectations about authorization and return content 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 front-loaded with the action and scope, followed by dense, non-redundant details about tenant_id semantics, return contents, and authentication. Aside from the harmless product-label prefix, every sentence earns its place by resolving a real ambiguity.

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?

There is no output schema, but the description tells the agent what each entry contains—the stored, containment-expanded query—and the prerequisite of an authenticated key. Combined with the annotations, this gives the agent everything needed to invoke the tool correctly and interpret its 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 0%, so the description must fully explain tenant_id, and it does. It defines tenant_id as an optional sub-label within the caller's own namespace, requires it to match the value used at registration, and clarifies that omission selects the namespace of queries registered without one rather than all queries. This completely compensates for the minimal 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 states a precise action and resource: 'list YOUR registered standing disruption queries' and clarifies it is 'scoped to the calling account.' This clearly differentiates the tool from siblings like register_standing_query, delete_standing_query, and list_disruption_events, so an agent can identify the correct operation without opening the schema.

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 strong contextual guidance: list only your own registered queries, and pass the same tenant_id you registered with. It also explains the critical non-obvious behavior that omitting tenant_id lists only queries registered without one, not all queries. It does not explicitly name alternative tools, but the scoping rules remove the main usage 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that results include entity counts and searchability, which is useful but not a deep behavioral disclosure.

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

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

A single, front-loaded sentence conveys the core action, target resource, and output highlights with no filler or redundancy.

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

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

With no parameters, strong annotations, and an output schema present, the description provides sufficient context for the agent to invoke this tool correctly. Nothing essential is missing.

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

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

There are zero parameters, so parameter semantics are not applicable. Per the baseline for zero-parameter tools, the description doesn't need to compensate for any parameter documentation 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 states a specific verb ('List'), resource ('configured verticals'), and additional output details ('entity counts and searchability'). This distinguishes it from sibling list tools like list_sources and list_disruption_events without ambiguity.

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

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

The purpose is clear enough that an agent would know to call it when it needs verticals information, but the description provides no explicit guidance on when to prefer it over alternatives or any exclusions.

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

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

The description adds useful behavioral context beyond the annotations: it is a write operation that persists state, is visible to future sessions through recall/get_site_skill, and accepts a constrained set of outcome values with an optional note. It does not detail append-vs-overwrite behavior, but the annotations already signal non-idempotent and non-destructive traits, lowering the burden.

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 compact and front-loaded: the main purpose appears in the first sentence, followed by the accepted values and the persistence behavior. Every sentence adds value, and there is no redundant restating of the tool name or schema.

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 three-parameter write tool with no output schema, the description covers the core semantics: what to record, allowed values, note format, and cross-session visibility. Minor gaps remain around whether repeated logging appends or overwrites and how the entity_id is obtained, but these do not prevent correct invocation.

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

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

With 0% schema description coverage, the description compensates well: it documents the allowed outcome values, clarifies that note is optional and gives a concrete example, and implicitly defines entity_id as the entity whose outcome is being recorded. entity_id itself is not explicitly described, but the name plus the description context make its meaning reasonably clear.

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

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

The description states a specific verb and resource: 'Record what actually happened with an entity' and defines the domain-specific outcome vocabulary (booked, visited, called, failed, abandoned, other). It also clearly differentiates this write-oriented tool from read-oriented siblings like recall/get_site_skill by framing it as the agent-side 'cookie' for future sessions.

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 context: use it to record an actual entity outcome so future sessions can see it via recall/get_site_skill. It does not explicitly name alternatives or state when not to use it, but the cookie analogy and persistence framing make the intended use case clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so no side effects are expected. The description adds useful behavioral context beyond annotations: the tool reads an agent-private profile rather than general data, and it enumerates the categories of state it surfaces, which helps the agent know what to expect.

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

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

The description is two sentences with no filler. The first sentence front-loads the result content, and the second sentence gives a clear usage directive. Every phrase 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?

For a zero-parameter, read-only tool with no output schema, the description covers what is returned, when to call it, and why it matters. It could be more explicit about the exact output shape, but the listed categories are sufficient for an agent to know whether this tool is relevant.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to explain about parameters. The baseline of 4 applies, and the description adds relevant context about what the profile contains rather than parameter details.

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 a specific verb ('Read') and resource ('YOUR agent profile'), and enumerates exactly what the tool returns: remembered preferences, recent searches, recent per-entity actions, and top entities. It also distinguishes itself from general search/retrieval siblings by emphasizing that this reads the agent's own stored profile.

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

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

The description explicitly says when to call it ('at task start') and why ('to reuse what past sessions learned'), including a concrete example about dietary defaults. It does not explicitly name when not to use it or name an alternative tool like remember, but the timing and purpose are clear enough to guide an agent.

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

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

The description goes well beyond the annotations by explaining the delivery mechanism, HMAC-SHA256 signing, the exact signature header format, and the fact that the secret is never echoed. The annotations already mark this as a non-read-only, non-idempotent operation, and the description does not contradict them. It could add what happens on duplicate registration, but the disclosed security and delivery details are strong.

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 dense sentences cover purpose, payload format, signing, secret handling, usage guidance, and tenant semantics without waste. The core purpose and key integration details are front-loaded, and every sentence earns its place.

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

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

Given there is no output schema, the description explains the event payload format by referencing list_disruption_events, covers signing verification, and clarifies tenant_id. The main gap is that it does not describe the registration response (e.g., whether a webhook ID is returned), but this is a minor omission for a tool whose activation behavior is otherwise clearly specified.

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 carries the full burden for explaining parameters. It does this well: url is the POST destination, secret is the HMAC signing key, and tenant_id is an optional namespace label used consistently with list_disruption_webhooks. Every parameter gains meaningful context beyond its bare type definition.

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 names a specific verb ('register') and resource ('disruption webhook'), and explains what the webhook does: disruption events are POSTed to a URL as structured JSON. It distinguishes itself from polling and references list_disruption_webhooks, making it clear this is the creation counterpart to the listing and deletion 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?

It explicitly says 'Use instead of polling when you want push delivery,' which tells the agent when to choose this tool over pulling from list_disruption_events. It also instructs that the same tenant_id should be passed to list_disruption_webhooks to see registered webhooks, providing a verification workflow.

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

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

The description discloses substantial behavior beyond the annotations: geo_ids expand through the containment hierarchy, the response echoes the EXPANDED query with query_id, corroboration_policy strictly rejects unknown fields, and tenant_id is a namespacing sub-label restricted to the caller's own account. These are non-obvious behavioral details an agent needs to predict 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 dense but every sentence carries operational value: purpose, when-to-use, expansion behavior, response shape, validation strictness, event delivery, and tenant scoping. It is front-loaded with the core purpose and then layers constraints in a logical order without 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?

The description is strong overall: it covers return behavior via query_id, how matching events are delivered, and how to address the query later. The only completeness gap is that two optional parameters, lang_scope and min_severity, are left undocumented despite zero schema descriptions and no output schema to clarify their role.

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

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

With 0% schema description coverage, the description compensates well by explaining geo_ids expansion, accepted disruption_types, expires_at format, exact corroboration_policy values, and tenant_id semantics. However, lang_scope and min_severity are not explained at all, leaving two optional parameters to be inferred from their 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 opens with a specific verb and resource: register a standing disruption query for continuous real-time monitoring of geo_ids and disruption_types. It clearly distinguishes this from historical sentiment tools by saying it is for ALERTING on future disruptions, not historical sentiment, and lists the exact accepted disruption types.

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

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

It explicitly states when to use the tool: when an agent needs alerting on future disruptions, not historical sentiment. It also explains how the registered query connects to list_disruption_events and registered webhooks, and how tenant_id ties it to list_standing_queries and delete_standing_query, giving clear operational routing.

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

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

The description adds significant context beyond the annotations: persistence across sessions and API-key rotation, the fact that SeaWeb's credential filter is a backstop rather than a guarantee, and that unlabelled secrets will be stored as written. This is exactly the behavioral nuance an agent needs when deciding whether to call this write tool.

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

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

The description is front-loaded with the core purpose, followed by concrete examples and then a necessary security warning. Every sentence earns its place; there is no filler or repetition of schema 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 two-parameter write tool with no output schema, the description covers what the tool does, when to use it, what not to store, and the real-world risk of the credential filter. The agent has everything needed to invoke it correctly and safely.

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

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

With schema description coverage at 0%, the description carries the burden of explaining the parameters. The examples like remember('dietary', 'vegan') and remember('party_size', '2') clearly show that key is a semantic label and value is the stored preference. It could be even more explicit about key uniqueness or value formatting, but the examples sufficiently bridge the schema gap.

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

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

The description states a specific verb and resource: 'Save a durable preference on YOUR agent profile', and clarifies that this is account-level memory surviving sessions and API-key rotation. The examples ('dietary', 'home_neighborhood', 'party_size') make the intended use unmistakable and distinguish it from sibling tools like recall and log_outcome.

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

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

The description explicitly says 'Use for defaults worth reusing' and gives concrete examples. It also gives a strong when-not: never store passwords, session cookies, or credentials. However, it does not explicitly name an alternative tool for storing credentials or for non-durable state, so the guidance falls just short of fully routing the agent to alternatives.

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

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

The description meaningfully goes beyond the all-false annotations by disclosing synchronous semantics ('Blocking'), tolerance for incomplete results ('best-effort'), and a specific side effect for storm mode ('creates a deep multi-perspective STORM agent research job in Postgres'). This is useful behavioral context beyond what readOnlyHint=false, idempotentHint=false, and destructiveHint=false convey. Minor gaps remain, such as whether standard mode has persistent side effects and what happens when wait_s expires.

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 compact: one front-loaded lead sentence followed by a scannable bullet list for 'method'. Slight redundancy exists — 'method selects the backend execution engine' restates what the lead sentence already implied via 'or STORM agent' — but overall every line earns its place and the structure aids comprehension.

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

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

The core behavior and the two execution modes are explained, and the presence of an output schema reduces the need to describe return values in prose. However, the interplay between 'depth' and 'method' is never addressed, 'wait_s' semantics are unstated, and there is no mention of relative cost, side effects, or when blocking terminates. For a moderately complex tool with no annotation help, these are nontrivial 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?

With 0% schema description coverage, the description carries full responsibility for explaining parameters, but it only documents 'method'. 'depth' is completely unexplained and confusingly defaults to 'standard' alongside 'method', inviting ambiguity about their relationship. 'wait_s' is only self-evident from its name, and its timeout/polling behavior is never stated — so an agent cannot reliably choose values for three of the four parameters.

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 first sentence, 'Blocking-best-effort research over SeaWeb's live crawl queue or STORM agent,' states a specific operation with named backend resources and behavioral qualifiers ('blocking', 'best-effort'). The 'method' section adds concreteness by spelling out the two execution engines. It is distinguishable from siblings like research_status, search_web, and search, though it never names them 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?

The description gives real selection guidance for the 'method' parameter: 'standard' for the existing SQLite crawl queue and 'storm' for deep multi-perspective research jobs. However, there is no when-to-use vs alternatives guidance — nothing tells the agent when to prefer research over search_web, search, recall, or get_details, nor any 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: the caller-scoped ownership check, identical 404-shaped error for missing vs. unauthorized jobs, absence of an existence oracle, rate limiting, and the heartbeat staleness rule that freezes estimated_wait_ms after 120s. This is substantial, non-obvious context that annotations alone would not convey.

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

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

The description is front-loaded with a one-line summary, then organized into caller-scoping/security, requirements/rate limit, and return semantics. Every sentence contributes distinct information, and the density is justified by the behavioral nuance it documents. No redundant or filler phrasing.

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

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

The description covers prerequisites, authentication refusals, rate limiting, error-equality behavior, conditional response structure, and the derivation of estimated_wait_ms. Since an output schema exists, the lack of an explicit status enum is not a meaningful gap. The tool is well-specified for correct invocation and response interpretation.

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 no parameter description for job_id (0% coverage), and the description never directly defines job_id. However, the phrasing 'Poll surface for a research job' and the ownership-check sentence ('job_id AND requester_key_hash') make it inferable that job_id is the identifier of the job to poll. It adds some meaning but does not fully compensate for the absent schema description.

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 'Poll surface for a research job,' which names a specific verb and resource. It further clarifies what is returned (status fields, results when completed), making the tool's function clear. However, it does not explicitly differentiate itself from sibling tools like research() or agent_job_status, so it stops short of a full 5.

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 gives clear context: the tool polls a research job and requires SEAWEB_LIVE=1 plus an authenticated caller, with anonymous callers refused and a rate limit of 30/min. It does not explicitly state when to choose this over alternative status-checking tools or when not to use it, so it lacks explicit exclusions/routing.

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/idempotent annotations, the description discloses matching order (exact diacritic-folded aliases first, then trigram-fuzzy), similarity scores, containment hierarchy for homonym disambiguation, and the meaning of an empty candidate list. This is strong behavioral transparency.

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

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

Three dense sentences, each earning its place: what the tool does, how matching works, and how to interpret an empty result. Information is front-loaded and there is no 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?

With no output schema, the description still explains the return shape: candidate geo_ids, similarity scores, containment hierarchy, and the empty-list case. Combined with annotations covering safety and idempotency, this is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly defines 'text' as a free-text place name and explains the output candidates, but it does not explicitly describe the 'limit' parameter's behavior or how it affects results.

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

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

Description states a specific verb ('lookup') and resource ('travel gazetteer'), maps free-text place names to candidate geo_ids, and ties it to other travel-vertical tools. This clearly differentiates it from siblings like search or get_entity.

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

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

The description gives clear context: use this when you have a free-text place name and need geo_ids for travel-vertical tools. It does not explicitly name alternatives or when-not-to-use cases, but the intended use is evident.

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/idempotent annotations, the description discloses substantial behavior: constraints validation and precedence, coordinate-based distance/sorting, location_needed note semantics, the SEAWEB_QUERY verdict meanings, and degraded-mode outage semantics. It also warns about banner lines and how to parse them—context not inferable from 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 front-loaded with a one-sentence purpose then parameter semantics, and the long response-parsing section is dense with operationally necessary distinctions (uncertain vs not_found vs degraded). It is not overly verbose for the complexity, but the banner/verdict explanation is lengthy enough that a tighter presentation might improve scannability.

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

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

For a complex tool with 7 parameters, no schema descriptions, and rich annotations, the description covers all essential behavior: parameter semantics, location fallback, constraints validation, output format, and error/verdict interpretation. The presence of an output schema covers formal return fields, while the description explains the non-obvious header line semantics, making it complete for safe 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 description coverage is 0%, so the description carries the full burden, and it delivers. Each parameter is explained: vertical via list_verticals(), intent as free text, location as neighborhood filter, goal as discover|book, constraints with allowed keys and rejection behavior, and lat/lng as WGS84 coordinates with sorting effects. This more than compensates for the bare 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 opens with a specific verb+resource: 'Search any SeaWeb vertical by natural-language intent.' This clearly distinguishes the generic cross-vertical search from vertical-specific siblings like search_restaurants and search_salons, and from search_web, by emphasizing 'any SeaWeb vertical' and returning canonical seaweb://{vertical}/{slug} entity cards.

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 provides clear usage context: use list_verticals() to enumerate verticals, pass free-text intent, and use recall() for stored preferences. It also gives explicit handling guidance (ASK the user for location on proximity queries rather than guessing). However, it never names alternative tools or states when not to use this tool, so the when-vs-alternatives guidance is only implicit.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses meaningful behavior: first-call embedding model load latency, deduplicated story clusters rather than raw documents, explicit zero rows, and named empty_aspects. These are exactly the kind of non-obvious behaviors an agent needs to 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 dense but every clause adds operational value: scope, return shape, data semantics, accepted values, defaults, related lookup, and a performance warning. It is front-loaded with purpose and alternatives before diving into output details, so an agent scanning quickly gets the decision-critical information 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?

With no output schema, the description fully explains return structure: aspect-by-time grid, cluster counts, variance, polarity histogram, language/source breakdowns, and source URLs. It also covers missing-data conventions and startup latency. This is unusually complete for a read-only aggregate query tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains geo_id, window_start/window_end ISO-8601 defaults, bucket granularity, aspects subset, and top_k via 'top-k canonical source URLs'. The only clear gap is 'langs', whose filtering semantics are left to inference from the field name and return breakdown.

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

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

The description states a specific resource (destination sentiment aggregates for Product A) and a clear use case ('how do travelers feel about X over time'). It explicitly distinguishes itself from real-time alert/standing-query tools, so an agent can tell it apart from siblings.

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

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

The description gives direct when-to-use guidance ('use for ... over time') and an explicit negative ('never for real-time alerts — that is the standing-query/event side'). It also directs the agent to resolve_geo for finding geo_ids, which is 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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses server-side behavior: the server 'tries to extract them from intent on its own' and explicit params win conflicts. It flags that dietary is a 'HARD filter... never relaxed' and corrects the bookable=False pitfall ('UNFILTERED, it does NOT mean "must not be bookable"'). This adds substantial behavioral context the annotations cannot convey.

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

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

Front-loaded single-sentence purpose followed by compact per-parameter lines using a consistent 'extract from X -> value' format with terse annotations like '(1=$, 2=$$, 3=$$$, 4=$$$$)'. Dense but earned; the only mild redundancy is saying explicit params are 'more reliable' and then that they 'always win on conflict'.

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 8 nuanced parameters and an output schema that covers return values, every input is documented with its extraction trigger, default, and edge-case semantics — including the hard-filter guarantee for dietary and the bookable=False unfiltered behavior. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 0%, and the description fully compensates: it explains location defaults, maps price_max to dollar tiers 1-4, enumerates the accepted dietary value set, gives party_size extraction examples ('party of 4' -> 4), and defines the goal values. This is precisely the meaning the bare schema titles omit.

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?

Opens with 'Search restaurants by natural-language intent' — a specific verb, resource, and invocation mode in one sentence. The intent-based framing distinguishes it from siblings like filter_restaurants (structured criteria) and get_restaurant (point lookup), and it scopes the domain to SF with the 'empty (default) = no filter, all SF' clause.

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 extensive when-to guidance: 'set these whenever intent implies them instead of leaving everything in free text', explicit params 'always win on conflict' with server-side extraction, and per-parameter extraction triggers like 'extract from any budget/price cue'. It never names an alternative tool or states when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only/idempotent/non-destructive; description adds useful behavior beyond that: same ranking/constraint behavior as search_restaurants, salons-only return set, and the cuisine slot being repurposed as a service-type filter while dietary is unused. That explains real quirks an agent would otherwise discover only after calling.

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 behavior statement is front-loaded, and the parameter block is a compact reference with short annotations per field. No filler or repetition; the length is justified by eight parameters and several domain-specific quirks.

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 an 8-parameter search tool with no schema descriptions, the description covers every parameter, the selection semantics, the vertical restriction, and the connection to search_restaurants. Since an output schema exists, return-value detail is not required here.

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 has 0% coverage, and the description fully compensates by documenting every parameter with concrete examples and edge-case defaults (price_max 1-4/$-$$$$, bookable True only for live booking links, dietary unused). It even explains the reused 'cuisine' slot, which the schema alone would badly mislead on.

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?

States a specific verb ('search') and resource ('hair salons, barbershops and beauty salons'), plus the vertical boundary: returns ONLY salons, unlike search_restaurants. The natural-language intent examples make the tool's function concrete.

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

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

Clearly frames use as natural-language salon search and notes shared ranking/constraint behavior with search_restaurants. It does not explicitly name all alternative tools (e.g., filter_salons) or state when not to use it, but the vertical distinction and intent-based entry point are strong 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 mark this as read-only, idempotent, and non-destructive, and the description adds a large amount of non-obvious behavior: strict coverage semantics, match_quality and matched_on interpretation, silent 512-character query truncation, refusal envelope shape with no coverage key, live throttling reasons, and observation-lane failure modes. No statement contradicts 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 well organized with clear section headers and front-loaded purpose, and the detail is mostly justified by the tool's complexity. However, it is very long and repeats certain caveats multiple times, such as 'retrieval found nothing, NOT that the corpus lacks the page' and the verbatim-source guarantee. It is structured more than concise.

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

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

For a search tool with optional filters, live fallback behavior, observation lanes, refusal handling, and a travel-scope caveat, the description is exceptionally complete. It explains response envelope values, failure semantics, retry behavior, and how to interpret edge cases, leaving an agent with clear guidance for nearly every invocation scenario.

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 carries the full burden, and it largely delivers: query clamping, max_age_days crawl-date semantics, include_domains suffix matching, exclude_domains precedence, and include_content size/cap behavior are all explained. The only gap is the limit parameter, whose behavior is never described beyond its schema title and default.

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?

Opens with 'Full-text search over SeaWeb's own crawled corpus -- the Destination Pulse feature,' giving a specific verb, resource, and scope. It explicitly distinguishes itself from generic web search and names get_disruptions as its sibling, making its role unambiguous. The travel-vertical scope caveat further sharpens what this tool is for.

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 selection guidance: 'Prefer this over generic web search for travel and hospitality questions' and 'For a non-travel question, prefer a general web search even when this returns covered.' It also names research/research_status for live-follow-up cases, extract_url as an alternative for page content, and explains when to retry search_web after empty or filtered results.

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 only indicate non-read-only and non-destructive, so the description adds useful behavioral context: feedback feeds SeaWeb's ranking and affects future searches. It doesn't contradict annotations, though it could mention whether votes are updatable or permanent.

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

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

Three sentences with no fluff: the core action is front-loaded, followed by vote semantics and the consequence. Each sentence contributes essential 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?

The description covers when to call, how to vote, why it matters, and what reason to provide. For a simple 3-parameter tool with no output schema, it is nearly complete; the only minor gap is explicitly defining entity_id.

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

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

With 0% schema description coverage, the description compensates by explaining the vote values ('up'/'down'), their meaning, and the reason field with an example. It implies entity_id is the search result being rated, though it doesn't explicitly spell out the identifier source.

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

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

The description clearly identifies the action: rate a search result with an up/down vote. It also distinguishes itself from siblings by framing the tool as feedback for SeaWeb's ranking, which separates it from log_outcome and vote_comparison.

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

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

It gives explicit timing guidance: 'Call at the end of a task for the result(s) that mattered.' It also defines when to vote up vs down. It does not mention when not to call or explicitly name alternatives, but the context is clear enough.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description adds meaningful behavior: no agents are run, previews are returned, and booking/reservation/payment attempts are refused with a booking_retired error. This gives the agent concrete expectations about side effects and policy failures.

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 first two sentences are near-duplicates, both saying the tool decomposes requests and returns a preview with specialist roles. The rest is useful and front-loaded, but the redundant opening reduces the conciseness score.

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 provides a sufficient high-level picture of the return value ('preview with specialist roles') plus parameters and an important policy constraint. It doesn't describe the exact output structure, but for a low-complexity preview tool this is adequate.

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

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

Schema description coverage is 0%, so the description fully carries parameter semantics. It defines task as a natural language goal/query and max_agents as the planner count with a default of 4 and range of 1-5, adding meaning beyond the bare schema types.

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

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

States a specific verb and resource: it decomposes a request into planned specialist roles and returns a preview. It also explicitly says it runs no agents, which distinguishes it from tools that actually execute agent teams.

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 context: this tool is for planning/previewing a decomposition, not for executing agents. It does not name alternative tools, but no direct sibling for teamwork preview is present, and the 'runs no agents' clarification provides usable selection 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 mark the tool as readOnly, idempotent, and non-destructive. The description adds useful behavioral detail beyond that, such as the specific backend dependencies checked and the lazy-loading behavior of the embedding model on first sentiment search. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then efficiently enumerates the specific health checks. Every clause adds useful information without fluff.

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

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

Given zero parameters, simple invocation, and strong readOnly/idempotent annotations, the description is complete enough for an agent to select and call the tool correctly. It specifies what is measured and the notable lazy-loading behavior, even without an 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?

The tool has zero parameters, so there is no parameter semantic burden for the description. The description explains the tool's scope without needing to document inputs, matching the baseline expected for a parameterless 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 what the tool reports: dependency health of the travel vertical service, listing specific dependencies (elasticsearch, postgres, redis) and the embedding model state. It is distinct from sibling tools like search_destination_sentiment or list_verticals, though it does not explicitly name a differentiating sibling.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of typical scenarios, prerequisites, or exclusions, which leaves the agent to infer that this is for checking service dependency health.

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 this is a non-read-only, non-idempotent action, and the description's word 'Record' aligns with a mutating operation. The description adds useful behavioral context by explaining how to attribute the verdict to agent vs. human and how to link the vote back to the originating comparison. It does not fully disclose whether duplicate votes overwrite or append, but the annotations already cover the main safety profile.

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 compact, front-loaded with the main action, and then gives targeted parameter guidance in short, readable sentences. Every sentence contributes useful information; there is no fluff or restatement of the tool name.

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

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

For a simple recording tool with one required parameter and no output schema, the description provides sufficient context to invoke it correctly. It explains the relationship to compare_search, the required winner values, the judged_by provenance rule, and the need to preserve query/track_b linkage. The omitted 'reason' parameter is optional given its default and therefore does not block 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?

With 0% schema description coverage, the description must carry the semantic load, and it largely does: it defines the allowed values for 'winner' ('A', 'B', or 'tie') and 'judged_by' ('agent' vs 'human'), and explains the role of 'query' and 'track_b'. The only gap is the 'reason' parameter, which is completely undocumented in both the schema and the description.

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

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

The description states a specific action ('Record an A/B verdict') and ties it explicitly to a sibling tool ('after compare_search'). It also defines the core domain terms 'winner', 'tie', and 'judged_by', making the tool's purpose unmistakable. This clearly differentiates it from similar comparison or logging 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 tells the agent when to use the tool ('after compare_search') and gives explicit instructions for provenance ('judged_by: agent for your own judgment, human when relaying the human's answer'). It also instructs the caller to pass the same query and track_b as the comparison, which is a strong usage constraint. It does not explicitly list when not to use it, but the context is clear enough.

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