Diver Atlas

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

Annotations already establish read-only and closed-world behavior. The description adds meaningful context beyond that by naming the return fields (status, reasons, verification, sources, canonical URL) and clarifying that the tool evaluates rather than recommends.

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, front-loading the tool's purpose and then the returned information. Every sentence carries useful signal.

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 absence of an output schema is offset by the description listing the return fields, and annotations cover safety. However, for a five-parameter suitability calculation, the lack of parameter guidance means an agent cannot confidently judge when to supply optional fields like deep_specialty or last_dive_months.

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 should explain the five parameters. It only implies that 'slug' identifies the plate; it does not explain certification levels, dive count, deep specialty, or dive recency, leaving most parameter meaning to the bare schema names.

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: a rule-based suitability check for one plate. It distinguishes its scope by noting that it does not recommend a centre, though it does not explicitly name sibling tools like get_site_plate or search_sites.

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 usage context is implied: check suitability for a single plate using certification and dive data. The exclusion 'Does not recommend a centre' is useful, but there is no explicit routing to alternatives or statement of when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond a content listing — no indication of whether results are scoped per country, how the verification breakdown is structured, or whether hub URLs are always present.

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 short sentence with no filler, and the most distinctive element (coverage plus verification breakdown) is front-loaded. It is efficient, though efficiency here partly reflects under-specification rather than tight editing.

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

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

For a read-only overview tool with no output schema and an entirely undocumented optional parameter, the description should explain the country filter semantics and what an unscoped call returns. Neither is present, so an agent cannot call it confidently.

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 is one parameter, country, with 0% schema description coverage and no required flag, yet the description never mentions it. The description therefore fails to compensate for the coverage gap: an agent cannot tell whether country is an ISO code, a name, or what omitting it returns.

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 the returned content (country/area coverage, verification breakdown, hub URLs) but has no verb and never states that it retrieves an overview report. An agent can infer the resource from the name plus the noun list, but it gets no scope boundary versus siblings like list_centres or get_latest_conditions.

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 when-to-use guidance, no mention of when to prefer this over sibling coverage/lookup tools, and no note that the country parameter is optional. The agent must guess the invocation context entirely.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful context beyond annotations by disclosing that diver names, emails, and user IDs are omitted and that verification is included, but it does not explain ordering, recency semantics, default limit behavior, or what 'verification' entails.

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

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

The description is three short, front-loaded sentences with little waste. The purpose is stated first, followed by privacy and verification notes, though 'Includes verification' is vague enough that it slightly weakens the otherwise efficient structure.

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 retrieval tool with no output schema, the description covers purpose and some data-handling context. However, it leaves meaningful gaps around the meaning of 'latest', how the limit parameter behaves, and what the returned condition reports contain beyond verification.

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 for the two undocumented parameters. It does not mention the required slug or the optional limit parameter, nor does it explain acceptable slug format or how limit controls result count.

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 and return type: timestamped condition reports for a plate. It is clear enough to distinguish this from sibling suitability or site tools, though it does not explicitly name or contrast with any alternative.

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

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

There is no explicit guidance on when to use this tool versus alternatives like check_suitability or get_site_plate. The description implies it retrieves latest conditions, but gives no conditions for use or exclusions.

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

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

Annotations already establish that this is a read-only, non-open-world operation. The description adds useful return-content context (verification, sources, canonical URL), but does not discuss missing-slug behavior, error handling, or response shape.

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?

It is a single efficient sentence with the key scope front-loaded. The jargon "plate" slightly reduces clarity, but there is no wasted 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 one-parameter read-only lookup with no output schema, the description gives a partial sense of what is returned but remains too vague about the structure and slug semantics to be fully self-contained.

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 mentions the slug parameter only by name and does not define its format, source, or meaning. With schema description coverage at 0%, this leaves the parameter largely undocumented.

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 operation (retrieving a full plate for a slug) and lists some contents, but "plate" is domain jargon and the description does not clearly distinguish this from siblings like search_sites or list_centres.

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 implies a lookup when you already have a slug, but gives no explicit guidance on when to use this instead of search_sites or list_centres, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one useful behavioral fact — the result set deliberately excludes phone, email, and ranking — but says nothing about filtering behavior, result volume, or pagination, so it adds little beyond the annotations.

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

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

It is short and front-loaded with the most important fact (what fields come back), but it is written as two clipped fragments rather than a sentence, so terseness comes at the cost of clarity rather than from it.

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 three-filter listing tool with no output schema and zero parameter documentation, the description should explain the filters and the shape of the list. It gives only a partial field inventory and an exclusion list, leaving the agent guessing about the core query mechanics.

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?

Three parameters (area, country, locality) have 0% schema description coverage, and the description says nothing about any of them — not their format, whether they combine as AND filters, or whether they are exact-match or substring. With the schema carrying no documentation and the description not compensating, an agent cannot use these filters confidently.

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

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

The description is a noun fragment ('Public centre fields already shown on centre pages') that never states the action; the reader must infer 'lists centres' from the tool name alone. It conveys the field scope of the result but not the verb or resource, and does nothing to distinguish it from siblings like list_species or search_sites.

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 statement of when to call this tool or which sibling to use instead. The only routing signal is negative scope ('No phone, email, or ranking'), which weakly implies 'use something else if you need contact data' but never names that alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only safety profile is covered. The description adds genuinely new context — that results carry a verification tier and a citable canonical URL — but says nothing about pagination, default limit, result ordering, or empty-result behavior for a 12-filter search.

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 waste, and the core purpose is front-loaded before the return-value note. It is efficient, though it spends its second sentence on output rather than on the twelve filters that need explanation.

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 12 optional parameters, zero schema descriptions, and no output schema, the description leaves the agent guessing about what each filter accepts and how results are shaped. It covers citation/verification metadata but is inadequate for a multi-facet search tool of this complexity.

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

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

Schema description coverage is 0% across 12 parameters, and the description explains none of them: q, area, locality, country, type, entry, level, current, verification, limit, and the two depth bounds are all undocumented. The only relatable phrase, 'verification tier', refers to the return value, not to how the 'verification' filter works.

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 (dive-site summaries), which is enough to distinguish it from siblings like search_guides or list_species. It stops short of explicitly contrasting itself with those siblings, so it lands at 4 rather than 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?

There is no statement of when to use this tool versus search_guides, get_site_plate, or get_atlas_overview, and no prerequisites or exclusions. Usage is only inferable from the name and the word 'summaries'.

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