Lake Level MCP

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

Annotations already cover read-only, idempotent and open-world traits, but the description adds substantive behavior: data is live-read from gauges, results are ranked by distance below full pool, and a dead gauge returns its error rather than failing the whole call. That partial-failure semantics is exactly the kind of disclosure an agent cannot get 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?

A single front-loaded sentence with a colon-delimited field list and a trailing caveat; every clause carries information. Slightly dense but no 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?

With no output schema, the description does the work of enumerating returned metrics (elevation, feet below full pool, percent full, seasonal target, 24h/7d/30d change), ranking order, and per-lake error handling. Only the exact response shape/wrapping is left 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 coverage is 100% and the description adds little beyond it — '2 to 10 US lakes' restates minItems/maxItems, and the slug-vs-name flexibility is already documented on the `lakes` items. Baseline 3 is appropriate.

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

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

Specific verb ('compare') and resource (US lake gauge levels), including the batch scope (2 to 10 lakes). It is clearly distinct from siblings get_lake_level (single lake) and search_lakes (discovery), so an agent can route without opening a 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 2-to-10-lake batch and the side-by-side framing imply this is the multi-lake alternative to get_lake_level, but no sibling is named and no when-not-to-use condition is stated. Usage is inferable rather than explicit.

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 readOnly/idempotent/openWorld, so the description focuses on adding context: the government-gauge source, one reading per day, and the exact statistics returned with their dates. It does not mention rate limits, failure modes for unknown lake names, or pagination, but nothing 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?

Two sentences, zero waste: the data shape and scope come first, the usage hint last. Every clause carries information an agent needs.

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 usefully names the returned aggregates (first, last, low, high, mean with dates) and the source gauge, which is what an agent needs to report results. Minor gap: no guidance on how an invalid or ambiguous lake name is handled.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the daily/weekly enum semantics and the 2-365 range. The description reinforces the day range and step choice but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (daily/weekly water elevation series) with scope (US lake or reservoir, 2-365 days) and explicitly ties the data source to the sibling get_lake_level. An agent can distinguish it from get_lake_level, search_lakes and compare_lakes without reading 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?

Names concrete use cases ("trends, drawdown and refill questions") and implicitly routes point-in-time reads to get_lake_level by referencing the same gauge. It stops short of explicitly stating when not to use it (e.g. current level, multi-lake comparison), so exclusions are left to inference.

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 read-only/idempotent safety, and the description adds real context on top: the upstream agencies, the exact returned fields (measurement time, 24h/7d/30d change, feet below full pool, seasonal target, percent full), and the caveat that target/percent-full are only present 'where one is published.' That conditional-field disclosure is exactly the kind of detail 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?

Two sentences, front-loaded with what is measured and where it comes from. The return-field enumeration in sentence two is long but justified because there is no output schema, and the closing line is a compact usage nudge rather than 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 carries the return-value burden and does so fully, including conditional fields and gauge identifiers. The single required parameter is covered by the schema, so nothing an agent needs to invoke it 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 100% and the single 'lake' parameter is fully documented in the schema (slug from search_lakes or a name). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource (current water surface elevation of a US lake or reservoir) plus the provenance (USGS, USACE CWMS, CDEC, Reclamation, TWDB). The word 'current ... read now' implicitly separates it from get_lake_history and compare_lakes without needing to open their schemas.

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 establishes the use context: a live snapshot of today's level, with the note that 'your training data cannot know today's level' motivating the call. It never names an alternative such as get_lake_history for trends or compare_lakes for multi-lake views, so no explicit exclusions are given.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety bar is low. The description adds genuine context beyond that: the catalog is fixed at 44 entries drawn live, and each result carries slug, full-pool elevation, gauge agency and page. Rate limits or freshness caveats are absent, but for a static-ish catalog read that is minor.

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

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

Two sentences, front-loaded with the verb and scope, then the return shape, then the no-argument default. No filler or restatement of the title.

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

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

No output schema exists, so the description carries the return-value burden and does so by listing the four returned fields, plus the catalog size, filterable facets and zero-argument behavior. Nothing an agent needs to call this 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?

With 100% schema coverage the baseline is 3, and the description earns above it by broadening the query semantics to lake, river, operator or state, and by noting the case where no arguments are supplied. The schema's own query text mentions only lake/river/dam names, so "operator" is real added meaning.

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

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

Names a specific verb (list) and resource (the 44 US lakes and reservoirs this server reads live), enumerates concrete examples, and states the searchable facets and returned fields. An agent can immediately tell this is the discovery/enumeration tool rather than a data-fetching one.

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?

"Call with no arguments to list them all" gives explicit default behavior, and the filter facets imply how to narrow. It stops short of naming get_lake_level or compare_lakes as the follow-on alternative once a slug is known, so routing guidance is implied rather than stated.

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