Umbra open SAR archive

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

The description goes far beyond the single annotation, detailing the specific color encoding rules, the exact components of the output (image block, caption, caution block), and conditional behavior (the caution text appears when polarization cannot be verified).

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 highly dense, front-loaded with the main function, and efficiently packs technical constraints and output details into coherent sentences.

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 high complexity of the transformation, the description is exhaustive. It explains the input requirements, the internal logic (color encoding), and the exact structure of the output result.

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?

Since schema coverage is 0%, the description should define all parameters. It only provides semantic value for the core 'urls' parameter, failing to define the purpose of 'db', 'asset', or 'max_size'.

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

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

The description clearly states the tool creates a 'change image' by combining 2-3 passes of a single site, which distinguishes it as a specialized composite generation function.

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 explicit requirements for proper usage: the STAC URLs must be for the same site and provided in time order. It also gives a critical exclusion regarding polarization.

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 provides critical operational context (two distinct processing modes, refusal of 'render' on public host) that is completely absent from the single readOnlyHint annotation. It explains the underlying methodology (backscatter vs. sunlight) which is vital for SAR data.

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 highly verbose and dense, relying on technical jargon (e.g., 'backscatter', 'provenance-stamped') and complex bulleted workflows. This excessive detail makes it difficult for an agent to quickly parse the core utility.

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?

While the tool is complex, the description is highly complete regarding its environmental and processing constraints (e.g., local vs public host). However, it is incomplete for practical invocation because it fails to define the semantics of the majority of its input parameters.

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?

Since schema coverage is 0%, the description bears the burden of explaining its parameters. It offers almost no semantic help for 4 out of 6 parameters (`db`, `asset`, `model`, `max_size`), leaving an AI agent guessing their function.

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 core purpose: returning a SAR-literate reading of a scene at a given URL. However, it spends significant effort on implementation details (vision keys, model vs. no key) rather than simply stating the function of the 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 is exceptionally clear about operational requirements, distinguishing between 'No key' and 'Key configured' modes. It explicitly dictates the necessary workflow (calling :func:`stamp_description`) and explains the value proposition over sibling tools like quicklook.

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 no annotations, the description carries the full burden and does so: it discloses return shape ({asset, path, bytes} vs size-and-hint), the public-host refusal and its error contents, the index requirement for local servers, and that unmatched asset names raise while listing v2 keys.

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 the two-step handshake, which is the most decision-critical fact. The asset-form enumeration is long but justified at 0% schema coverage; a few passages (e.g. repeated public-host detail) could be trimmed without loss.

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?

An output schema exists, yet the description still usefully previews return values. Behavior, prerequisites, and error paths are complete; the only missing piece an agent needs is guidance on dest_dir.

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 compensate. It thoroughly documents url (STAC URL, filename, or stem with index resolution), asset (product types, v2 keys with collision suffixes, filenames, and the gec vs gec_2 distinction), and confirm semantics. dest_dir is left completely undocumented, leaving one 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?

States a specific verb and resource ('Download one asset of an item to local disk') plus the size-check gating constraint. It distinguishes itself from siblings by referencing get_item-style resolution and the local/hosted server distinction.

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

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

Explicitly prescribes a two-step workflow: call with confirm=False to get size, then confirm=True to fetch. It also states the when-not case (public host refuses confirm=True) and the alternative remedy (download locally or run a local umbra-mcp server).

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 declare readOnlyHint, so the description carries most of the burden and does: backend selection (`local` unset → on-disk index vs live S3 walk, Canopy token), that no model is called, that `limit` is ignored on the local whole-archive GROUP BY path, that sub-two-pass sites are dropped by cadence/span gates, and that non-positive values raise ValueError. It even documents output field semantics and href ordering.

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 purpose and usage routing are front-loaded, but the body is roughly 1,500 words of dense prose with heavy backtick formatting and repeated framing ("orthogonal to", "is the twin of", "It gates the ... `rank_by` measures") restated for nearly every filter. The `rank_by` paragraph alone runs several hundred words; a parameter table or three-line-per-param pattern would convey the same semantics in a fraction of the length.

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 25-parameter discovery tool with an output schema, this covers selection, ranking, backend differences, filter interactions that are non-obvious (pool-scoping `start`/`end` vs whole-site `active_*`), failure modes, and what the return payload contains. Nothing an agent needs in order to call it correctly is left implicit.

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% across 25 parameters, and the description compensates thoroughly — dates accept ISO, bare year/month, or relative expressions; `bbox` is `[min_lon, min_lat, max_lon, max_lat]` WGS84; `intersects` is mutually exclusive with `bbox`/`place`; `rank_by` values are enumerated with the exact axis each ranks on. It also explains how paired bounds compose (`active_since` + `active_before`, `min_span_days` + `max_span_days`).

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 a specific verb and resource: "Rank the archive's most repeat-imaged sites," and immediately frames its role as the discovery step before `change` / `timescan` / `stack` / `pick_change_interval` / `narrate_change`. It also distinguishes itself from `search_catalog(area=..., fuzzy=True)` so an agent can pick between them without reading 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?

States explicitly when to reach for it ("the discovery step *before* every analysis verb", no site known in advance) and names alternatives with the condition that selects them (`search_catalog` with `fuzzy=True` when the site name is roughly known, before trying `semantic=True`). It also gives concrete filter recipes tied to intents (live monitoring targets, slow-change targets, newly-appeared vs long-established sites).

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 is highly transparent about operational requirements, detailing the need for a pre-built scene-embedding index, required API keys, and the deterministic nature of the ranking process (cosine similarity). This adds massive context beyond the simple 'readOnlyHint: true' annotation.

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?

While highly detailed, the initial paragraphs define the scope concisely and front-load the purpose. The subsequent technical explanation is dense and long, but the length is necessitated by the complexity of the underlying workflow (embedding index dependencies).

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?

This is a maximally complete definition for a complex, data-intensive tool. It outlines prerequisites (index build), operational constraints (API keys), and specifies the utility of the output data (use href with 'get_item'/'quicklook').

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?

Since schema coverage is 0%, the description must carry the full burden. It successfully adds semantics to all key parameters, explaining what 'asset' refers to (product quicklook source), what 'model' must match (the index embedding model), and the purpose of 'top_k' (ranked matches).

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 provides an extremely clear purpose: to find archived scenes that 'look like' a specific URL acquisition. It clearly defines the scope as visual, contrasting it sharply with metadata searches like those performed by 'search_catalog'.

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 explicit guidance on when to use this tool versus alternatives. It contrasts its visual, embedding-based ranking mechanism against the metadata filtering of 'search_catalog,' leaving no ambiguity for the 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?

readOnlyHint=true is consistent with a pure retrieval tool, and the description adds real context beyond annotations: index/key requirements, model-match failure mode, and that the sole model call is text embedding. It also discloses the return shape (compact records with href usable by get_item/quicklook, plus attribution), though it doesn't mention pagination or result limits.

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

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

Front-loaded with purpose and mechanism, then prerequisites, then return shape — a logical order with little waste. The heavy markup (double backticks, bold) and some redundancy around the embed database make it slightly longer than necessary.

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

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

Covers purpose, prerequisites, failure mode, and hand-off to get_item/quicklook; an output schema exists so return values needn't be spelled out. The gaps are the two undescribed tuning parameters, which matter for controlling result volume and similarity threshold.

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 carry parameter meaning. It does well for `query` (plain-language examples like 'ships at a berth') and `model` (must match the joint CLIP model used at index time), but `top_k` and `min_score` are never mentioned — notably that min_score is a cosine-similarity threshold, which is not inferable from the name 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?

States a specific verb+resource ('find archived scenes matching a plain-language query over their imagery') and names the mechanism (text-to-scene CLIP embedding search). It explicitly contrasts with the sibling find_similar by noting the only model call here is text-to-vector, so an agent can distinguish the two without opening 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?

Gives clear prerequisites: the index must be built via `umbra embed build` and the query must use the same joint CLIP-family model as the index, with dimension mismatch surfaced as an error. It implies the alternative (find_similar for image queries) but never states when *not* to use it or how it compares to search_catalog for metadata filtering.

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 readOnlyHint annotation already establishes the safety profile, and the description adds meaningful context by identifying Nominatim as the external service and documenting the returned bbox/display_name structure. It does not discuss rate limits, ambiguity handling, or error behavior, but it adds real behavioral detail beyond the annotation.

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

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

The description is two sentences, front-loaded with the core purpose and followed by the return shape and usage. Every sentence earns its place and there is no redundant 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 one-parameter geocoding tool with an output schema and read-only annotation, the description covers purpose, output shape, and sibling integration adequately. Minor gaps remain around no-match behavior and result ambiguity, but nothing essential is missing for 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?

Schema description coverage is 0%, so the description must carry the semantic burden for the single required parameter. It does this by describing query as a free-text place name, which is more informative than the bare schema field name, though it does not give examples or format constraints.

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: resolve a free-text place name to a bounding box. It names the underlying service (Nominatim) and clarifies the exact output shape, making the tool easily distinguishable from catalog search or scene 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 explains the intended workflow: inspect the returned box before searching, or pass it directly to search_catalog's bbox. This gives clear usage context and names the relevant sibling, though it does not explicitly state exclusions or failure cases.

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?

There is no contradiction with readOnlyHint=true. The description goes well beyond annotations: it discloses that zero matches is an error, multiple matches return candidate STAC URLs to re-pass, indexed snapshots are preferred over live re-fetch to avoid asset-name disagreement, and a token enables a commercial-archive lookup by keyed 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?

Core purpose is front-loaded in one line before the resolution rules, and nearly every sentence adds operational information. It is nonetheless long and partially repetitive — the rule that filenames/stems still resolve from the local index when a token is set restates earlier resolution logic.

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 tool with an output schema, this is more than sufficient: it covers input forms, deployment differences, failure modes, and the retrieval-on-demand role relative to ``search_catalog``. The card contents are also summarized despite the output schema already existing.

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 single ``url`` parameter has no description at all in the schema, so the description carries the full burden — and it does, enumerating the three accepted forms, the resolution mechanism (stem matched against asset hrefs), the token-gated commercial path, and error/candidate behavior.

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 opening sentence states a specific verb and resource: 'Return the full context card for one item.' The body distinguishes its retrieval semantics from ``search_catalog`` (indexed snapshot vs. live re-fetch) and from other catalog tools, though that differentiation is embedded in detail rather than stated crisply.

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 explains exactly which inputs are accepted and how each resolves — sidecar JSON URL, product filename, acquisition stem, or bare acquisition id under a token — and notes the ``umbra index fetch`` prerequisite for local servers. It is called 'the retrieval complement to ``search_catalog``', which implies the follow-up use case, but never states an explicit 'use this after a catalog hit / do not use for searching' rule.

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 readOnlyHint annotation, the description discloses important behavioral context: the index may or may not exist, searches become live S3 walks without it, and it explains staleness and several field meanings including datetime_suspect, quarantined_future_count, and unique_captures. This is substantive context that helps an agent interpret the tool's output and trade-offs.

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 then adds useful field semantics. It is somewhat long because it explains return fields that may already be documented in the output schema, but every sentence remains informative 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?

Given zero parameters, a readOnly annotation, and an output schema, the description provides everything an agent needs: what the tool reports, why to use it, and how to interpret key fields. No critical context appears to be 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?

The tool has zero parameters, so the baseline is 4. The description correctly does not invent parameter details, and the input schema is empty and fully covered.

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: 'Report on the local catalog index'. It also explains what the report is for, but does not explicitly contrast the tool with the sibling search_catalog or other stats tools, so it falls short of full sibling differentiation.

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: 'Lets a long-running agent decide whether searches will be instant (index present) or pay a live S3 walk, and how stale the snapshot is.' This tells the agent when the tool is valuable, but does not name an alternative tool or state 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?

The description goes far beyond the single annotation (`readOnlyHint: true`) by detailing complex behavioral traits. It outlines that the tool streams Umbra COGs, requires specific server environments, and conditionally returns two entirely different payload structures based on the presence of a vision key.

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?

While highly technical and dense, the information is logically structured. It flows from core purpose to specific constraints and then to operational modes (public vs. local). The density is justified by the complexity of the tool itself.

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 definition is exceptionally complete for such a complex tool. It covers input prerequisites (STAC format, order, polarization), execution environment constraints, and the two distinct output schemas (raw kit vs. provenance object), leaving no ambiguity about its function or use.

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

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

Given that schema description coverage is 0%, the description is highly effective. It provides the necessary context for the `urls` parameter (STAC URLs, must be in time order), and sets expectations for the results, which informs how the agent should interpret the context of the input fields.

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 purpose is clearly stated in the first sentence: 'Return a grounded reading of what changed between passes.' It immediately distinguishes itself as a sibling of 'describe_scene,' defining its unique function as narrating change based on deterministic data, which is critical for differentiation.

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 stringent operational guidelines, including a refusal of mixed polarizations and a detailed breakdown of required setups (public vs. local hosting). It dictates precisely how inputs must be ordered (time order) and when to expect specific output formats.

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?

This description is remarkably transparent. It explains the underlying mechanics (co-registers into a 'to_stack' cube, reduces with 'stack_stats'), defines the criteria for success (furthest clear of the speckle floor), and handles failure modes (returning 'None' if insufficient data exists).

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?

While the description is quite lengthy, its detailed nature is justified by the technical complexity of the algorithm. Every sentence serves to explain a critical constraint or purpose, meaning there is zero wasted 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?

The tool is comprehensively defined. It covers input constraints (required `load` extra, no mixing polarizations), output behavior (what the returned fields mean), logical termination conditions, and its role in the overall data analysis architecture.

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?

Given the 0% schema description coverage, the description is vital. It explains the semantic constraints of the parameters, such as why 'crs' is used (to weigh equal ground) and that 'max_size' and 'change_threshold_db' must align with 'stack_stats'.

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 purpose is stated with surgical precision: it scans a whole series and names the *pair* of passes with the greatest measurable change. It explicitly differentiates itself from narrating tools by defining its role as a measurement and selection step, not a modeling 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?

The description provides a complete workflow explanation, detailing why this tool is necessary before calling `narrate_change` or `change_composite`. It defines the 'before and after' use case, ensuring the agent understands its placement in the analytical pipeline.

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?

Since annotations are minimal (`readOnlyHint: true`), the description bears the full burden and excels. It explains critical operational behaviors like caching (that `max_size` is ignored when a cached thumbnail is smaller) and the generation of JSON sidecars.

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?

While the description is lengthy, its complexity (caching, rendering modes, environment dependencies) necessitates the detail. The most critical information—the purpose and default behavior—is placed upfront.

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 definition is highly complete. It outlines the return type, operational limits (refusal vs. streaming), resolution behavior, and external requirements for high resolution (e.g., local server/`get_item`), leaving no major functional gaps for the agent.

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

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

With 0% schema description coverage, the description provides vital semantic context for each parameter. It explains the functional meaning of `preview` (baked, render) and how `max_size` interacts with the caching mechanism, adding significant meaning beyond simple schema typing.

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 resource ('a scene's quicklook PNG') and the action ('Return'). It differentiates itself from general asset retrieval by specifying the format (PNG image block) and the underlying logic of the 'quicklook' function.

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 specific usage constraints, explaining that baked previews prefer `preview="auto"` and detail the conditional behaviors of `preview="baked"` (refuses) versus `preview="render"` (streams, requires [viz]). This tells the agent exactly when different modes are viable.

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 simple `readOnlyHint`, the description provides crucial behavioral traits: it specifies the return format (compact cards, not full STAC JSON), the determinism of the search (no model call unless `semantic=True`), and the explicit logic behind `min_score` dropping weak matches.

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?

While the description is exceptionally dense and long, its structure follows a logical pattern of parameter-by-parameter definition, ensuring that despite its size, no critical information is lost or poorly placed.

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 high complexity and the fact that the input schema provides virtually no documentation, the description is maximally complete, explaining prerequisites (like the need for a task-embedding index for `semantic=True`) and output implications.

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 entire semantic weight. It defines units (WGS84, degrees, meters), syntax (ISO format vs. relative expressions), and the specific geometric requirements for complex parameters like `bbox` and `intersects`.

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 tool clearly states its core function: 'Search Umbra's catalog and return compact context cards.' It immediately distinguishes itself from potential alternatives by detailing the extensive filtering capabilities.

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

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

The description provides detailed decision matrices for usage, specifically comparing and contrasting: `bbox` vs `intersects`, `fuzzy` vs `semantic` filters for 'area', and specifying when to use `local` to target different backends (on-disk vs authenticated archive).

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 readOnlyHint=true: it discloses the cost model (a header read per pass, kilobytes, no pixels, no co-registration), that no model is called, and how unreadable sources are treated differently from mixed ones. These are exactly the traits that determine whether an agent should spend a call here.

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 the core question, then usage, then returns, then the trivial-agreement caveat — a sensible order. Some prose is dense and could be trimmed (the paragraph re-explaining return keys), but nearly every sentence carries decision-relevant 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?

With an output schema present, the return-value narrative is partly redundant, but the description still supplies what the schema cannot: cost, the refusal-vs-unreadable distinction, and the '(unrecorded)' trivial-agreement case. The only real hole is that the inputs themselves are left unexplained.

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% for two parameters, yet the description never defines them: 'urls' is only obliquely implied by talk of passes and assets, and 'asset' (default GEC) is never mentioned at all. The heavy return-value discussion does not compensate for undocumented inputs on a tool with zero schema coverage.

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 ('check whether a site's passes are one measurement') and makes the distinction from stack_stats concrete by naming the exact failure mode it pre-empts (a calibrated pass differenced against an uncalibrated one). An agent can choose between this and stack_stats without opening either 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?

Gives explicit when-to-use guidance in two named situations: after a stack_stats provenance refusal (with the concrete remedy, groups[0]["hrefs"]) and before measuring a long series the caller did not assemble. It also notes the common case where the check is trivially satisfied, which steers agents away from over-using 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 only say readOnlyHint=true; the description goes well beyond by declaring no model is called, arithmetic over streamed COG overviews, results reproducible and safe to quote, and by warning that Umbra's open products are not radiometrically calibrated so decibel values are relative. It also discloses payload-size cost for block_series and the resolution trade the caveats record.

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 the core purpose and the sibling contrast, then organized by parameter group with clear paragraph boundaries. It is long, and the speckle pedagogy ('it is the interference pattern coherent illumination makes on rough ground') is more explanation than an agent strictly needs, but almost every sentence either sets policy or explains a default.

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?

An output schema exists, so return shapes need not be enumerated, yet the description still names the extra keys (spatial, peak_block, grid_text, caveats) that only appear when specific flags are set — the one thing a schema check would not reveal. For a complex 11-parameter analytics tool with an unsafe-to-misread numeric output, nothing an agent needs to call 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 coverage is 0%, so the description must carry the load; it explains crs (utm vs EPSG:4326 and why areas become None), extent (intersection vs union semantics), bbox format and purpose, blocks (N x N, 0 default, 6 a good default), block_series dependency on blocks, speckle_filter values, speckle_window (odd, 5 default), and change_threshold_db's role. Only asset and max_size go unexplained, which is a minor gap at 11 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?

States a precise verb and resource — measure how much a site changed across its passes, as numbers — and explicitly contrasts itself with change_composite and timescan ('those return a picture of *where* change is, this returns the *how much*'). An agent can route between these three siblings from the description alone.

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?

Gives explicit when-to-use conditions for each optional behavior: ask for blocks whenever the question is *where on this site*, or when a scene-wide mean looks small but change_composite shows a hot spot; use block_series only when the shape of history is the question; use speckle_filter when change is small or numbers look noisy, and leave it off for fine structure. Also states an input exclusion: refuses to mix polarizations.

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

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

Adds substantial behavior beyond readOnlyHint: it discloses shape validation, that CC-BY and the AI-interpretation note are stamped by the library rather than by the model, and that a deterministic caveat is appended when the image is a smaller baked preview. The 'stamping' language sits in mild tension with readOnlyHint, but the text implies an enriched return value rather than persisted mutation, so it is not a 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?

Front-loads the verb-plus-resource statement, then layers the workflow and side effects in a short paragraph. A few phrases ('the interpretation boundary for the no-key kit path') are jargon-heavy, but no sentence is redundant.

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 an output schema present, return values need not be explained, and the description covers the input contract, the validation behavior and the provenance rules. The remaining gap is the undocumented asset/item_id parameters, which the description never mentions.

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. It fully documents the required `reading` object's expected keys and meaningfully describes the conditional `image` argument, but leaves `asset`, `model` (only obliquely referenced) and `item_id` unexplained.

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 ('Validate a client-produced scene reading and stamp provenance') and frames the tool as the interpretation boundary that consumes what ``describe_scene`` produced. An agent can distinguish it from describe_scene, though it does not explicitly distinguish itself from stamp_narration, its nearest 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?

Gives a clear call order: read the picture describe_scene returned, formulate {summary, observed_features, confidence, caveats}, then pass it here. It also states the consequence of skipping it ('until this returns, the reading is unvalidated prose'). It stops short of naming exclusions or contrasting with stamp_narration.

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?

readOnlyHint=true is already declared, so the safety profile is covered; the description adds that the tool validates and that the stamped object retains the grounding numbers. It does not say what happens when validation fails, or clarify that 'stamping' produces a returned object rather than persisting state — a genuine ambiguity given the word 'stamp'. Not a contradiction of the annotation, but an unresolved tension.

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?

Short enough, but front-loading is weakened by embedded reStructuredText markup (':func:`stamp_description`') that adds noise rather than meaning for an agent reader. The second sentence carries the useful operational detail; the first is fine.

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

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

Output schema exists, so return values need no explanation, and the description correctly identifies the input pairing. But for a five-parameter validation tool with zero schema coverage and a subtle read-only-versus-stamp question, it leaves too much unstated: extra parameters, validation failure mode, and what 'provenance' is attached to.

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 five parameters, and it only speaks to two: the 'reading' JSON and 'change_stats'. asset, model, and item_ids go entirely unmentioned in both schema and prose, leaving the agent to guess their meaning and defaults.

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 pair of verbs (validate, stamp provenance) against a specific resource (client-produced change narration), and names its sibling stamp_description so the agent can distinguish it. Not quite a 5 because 'stamp provenance' alone doesn't tell the agent what the output object looks like without help from the annotation/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?

Places the tool clearly in a workflow: it consumes output from the no-key narrate_change kit and must be fed the JSON produced plus the change_stats grid. That is a real usage condition, not just an implied one. No explicit when-not or failure-path guidance, 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=true, and the description adds genuine value: it explains the semantics of the output (per-pixel temporal statistics, bright areas = activity) and states it returns an image block plus attribution. It doesn't touch auth or rate limits, but for a read-only summarization tool this is above the bar.

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 tight sentences with the core transformation front-loaded and the elaboration following. Efficient, with little wasted text, though the output note could be merged more cleanly.

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 four parameters at 0% coverage and no output schema, an agent needs more than this: the meaning, allowed values, and defaults of asset/db/max_size are unknown. The description does cover the return shape, but the parameter gaps make it incomplete for 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?

Schema description coverage is 0% across four parameters, so the description must compensate. It only clarifies the required 'urls' parameter (STAC URLs of passes) and leaves db, asset, and max_size completely unexplained, leaving most of the schema opaque.

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 transformation: 'summarize a whole time series into one activity image,' elaborated as per-pixel temporal statistics where bright areas mark activity. This is distinguishable from siblings like quicklook and stack_stats, though it doesn't explicitly contrast with them.

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

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

Says to pass STAC URLs of a site's passes, which implies when the tool applies, but there is no explicit when-to-use vs when-not, and no named alternative such as quicklook or change_composite for overlapping needs.

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 no annotations provided, the description carries the full burden and does so well: it discloses idempotent delta semantics, persistent state in the catalog index meta table, reset baseline behavior, backend behavior, and that no model is called. It also explains that the result is produced by deterministic set arithmetic and returns context cards for downstream tools.

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 key delta behavior and organized logically into workflow, parameters, state, and downstream use. It is somewhat long and occasionally narrative, but the length is largely justified by the tool's complexity and the absence of schema descriptions.

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 10 parameters, no annotations, and a complex stateful monitoring workflow, the description is complete enough for an agent to invoke it correctly. The existence of an output schema means return values need not be fully enumerated, and the description still adds useful downstream context.

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

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

Schema description coverage is 0%, so the description must compensate for all 10 parameters, and it does: it explains place geocoding, area substring and fuzzy matching, bbox, products, start/end bounds, name-derived watch identity, reset, and local backend selection. This adds substantial semantic meaning beyond the bare schema types and defaults.

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: reporting only acquisitions that are new since the last check of a site. It explicitly distinguishes the delta behavior from returning a whole list, and links the filters to the sibling search_catalog workflow.

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

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

It describes the standing-monitoring workflow directly: run the same watch repeatedly and act only on what changed. It also explains reset behavior, independent watches via name, and backend choice via local, leaving little ambiguity about when and how to use it.

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