mast_observations

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

With zero annotations, the description carries the full burden and does it well: it discloses no-auth access, name-resolution-to-cone-search chaining with a fallback path, that include_calibration defaults to false (science-only by default), that include_products returns data products for only the top 3 observations, that preview_image downloads and saves an image file as a side effect, and the caps (radius max 5, limit max 50). These are exactly the non-obvious behaviors an agent needs before 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?

Purpose and examples are front-loaded, then a structured Args block one-parameter-per-entry, so every line earns its place even at this length. Slightly verbose prose in a few entries (e.g. the preview_image parenthetical) keeps it from a 5, but the length is justified by 13 undocumented parameters.

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 13-parameter, no-annotation, no-output-schema tool this covers nearly everything an agent needs: inputs, defaults, caps, side effects, and partial hints about returns (observation count, top-3 product expansion, inline image). The return shape of an observation record itself is not described, which is the one gap given no output schema exists.

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 fully compensates: all 13 parameters get meaning, accepted formats (degrees, '2024-01-31' or '2024'), defaults (radius 0.05, limit 10), maxima (5, 50), matching semantics (partial match for instrument and product_type, `*`→`%` for wildcards), and precedence rules between object_name and ra/dec. Nothing is left to guess from 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?

States a specific verb+resource: search MAST (NASA/STScI space telescope archive) observations, with the scope qualifier that no authentication is required. The two inline query examples ('M31 observed by JWST', 'Hubble Orion Nebula observation log') make the resource concrete. It does not explicitly differentiate itself from archive siblings such as cadc_observations or alma_search, 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?

It routes usage inside the tool well: object_name is preferred over raw coordinates and is resolved via Sesame, falling back to a target_name wildcard search when resolution fails; ra/dec are only used when object_name is omitted. What's missing is any external routing – no statement about when to prefer cadc_observations or alma_search instead. Clear context, but no explicit exclusions.

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