MANNA

Cancel a running async TAP job. Sends UWS DELETE upstream. Idempotent: aborting an already-deleted or expired job returns the same {job_url, phase=ABORTED} shape rather than raising (abort_job swallows the 4xx). On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Count observations/sources near a target in one call (resolve -> select -> COUNT). Selects an archive by its curated `count_target` and runs the archive-correct positional COUNT: q3c for Data Lab, CONTAINS/CIRCLE for Gaia's gaia_source and ESO's obscore, INTERSECTS + COUNT(DISTINCT member_ous_uid) for ALMA. An archive whose count_target is mode='async' runs with a bounded poll. Returns `count` (int) plus a `resolved` block and a `plan` block (chosen_archive, table, endpoint, adql, count_expr, mode, alternatives, usage_notes). If a slow async job outruns the poll budget, returns `{"status":"pending","count":null,"job_url":...,"next_steps":...}` — poll get_async_job_status(job_url) until phase=COMPLETED, then get_async_job_results(job_url). Pass job_url back verbatim; it is the job's only handle (no server-side job id). Soft-fails (no error_class) on an unresolvable target or when no archive offers counting. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Introspect a specific IVOA service: its capabilities, and for TAP services its tables and columns. Returns {ivoid, title, description, capabilities, tables, truncated, total_tables} (plus matched_tables when table_filter is used). Use after search_ivoa_registry to learn what's queryable on a specific service before composing ADQL via run_adql_query. Each table normally carries its full column list. For a very large service the response degrades to a table *catalog* (name + description + column_count per table, no per-column detail) and sets truncated: true. When that happens, either pass table_filter='<keyword>' to narrow to the tables you want (a narrow match returns their columns inline), or get one table's columns by querying tap_schema.columns WHERE table_name = '<table>' via run_adql_query (or describe_table for curated tables). See the returned hints. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Curated quirks + the real column list for one archive table. Returns the table's actual columns (name + datatype, fetched live from the archive's tap_schema.columns) alongside table-specific curated facts: missing standard columns, value enums for filterable fields, notes, and cross_refs to related tables. For a known archive, exactly one of these is always present: * `columns`: [{"name": ..., "datatype": ...}] — the real column list. Project these explicitly rather than SELECT *. * `column_list_recipe`: the query to run yourself, if the fetch failed. `known: false` means only that we carry no curated notes for the table — for a known archive the column list is still returned. Use `describe_ivoa_service` to discover which tables an archive has, or `list_archives` for valid archive short_names. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Find observations of a target in one call (resolve -> select -> search). A purpose-driven workflow over resolve_target_name + list_archives + search_images_by_position / search_catalog_by_position. Pass an object name (auto-resolved) or explicit 'RA DEC'; optionally steer archive choice with `waveband` or an explicit `archive`. Returns the standard inline tabular envelope (same shape as search_images_by_position / search_catalog_by_position — typed `columns`, `rows`, explicit `truncated` bool; note this workflow tool's envelope does NOT carry the `query_fingerprint` / `save_recipe` cache fields the primitive tools attach — call the underlying search_images_by_position / search_catalog_by_position directly if you need those) plus: - `resolved`: {target, ra, dec, frame} — the coordinates actually used. - `plan`: {service, chosen_archive, endpoint, alternatives, usage_notes} — how the archive was picked, and its curated gotchas. Read `plan.usage_notes` before trusting the rows. Soft-fails (no error_class) when a name can't be resolved ({"resolved": false, ...}) or no archive matches the filter ({"count": 0, "hint": ...}) — recover by adjusting the target/filter or dropping to the atomic tools with an explicit endpoint. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Return access info for a COMPLETED async TAP job. The server does NOT fetch the result bytes. It returns the upstream job_url, the direct result_url, and a pyvo fetch_recipe so the client loads the data itself (e.g. in a Jupyter kernel). Anonymous access only. After calling this, execute the returned fetch_recipe code with your code-execution tool to load the data. The query already ran — do not re-submit it. If the job is not yet COMPLETED, raises job_not_ready (retry_strategy=poll). If the job ended in ERROR, raises tap_query_error with the upstream message. If the archive no longer has the job, raises job_gone (retry_strategy=abandon). On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Fetch the live UWS phase for an async TAP job. Returns {job_url, phase, started_at, ended_at, error_message, archive}. Phase is read live from the upstream service; no local caching. Phases per UWS spec: PENDING, QUEUED, EXECUTING, COMPLETED, ERROR, ABORTED, ARCHIVED, HELD, SUSPENDED, UNKNOWN. The LLM branches on the string. If the archive has deleted or expired the job, this raises job_gone (retry_strategy=abandon) — re-submit rather than continuing to poll. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

List the IVOA archives this server has first-class knowledge of. Each entry includes the archive's endpoint URLs (TAP / SIA / SCS), waveband, description, notable tables, and **usage_notes** — short agent-facing strings capturing archive-specific gotchas like non-standard table locations, sync-vs-async routing recommendations, target-name conventions, and ADQL quirks. Call this FIRST when planning a query against an archive whose behavior you don't already know — it'll save you the trial-and-error of discovering quirks through failed queries. The notes are curated based on real friction encountered while building the server. Pass `short_name` and/or `waveband` to narrow the result. With no arguments it returns every known archive (the usage_notes are verbose, so prefer `short_name` once you know which archive you need). Archives not listed here still work via `search_ivoa_registry` followed by `describe_ivoa_service` / `run_adql_query` — this tool only covers the well-known set. Returns: { "archives": [ { "short_name": "...", "display_name": "...", "host_substrings": ["..."], "tap_url": "...", "sia_url": "..." | null, "scs_url": "..." | null, "waveband": "...", "description": "...", "notable_tables": ["..."], "usage_notes": [ "Short agent-facing strings — read these BEFORE composing " "a query. They capture real gotchas like non-standard " "table names, required mode='async' routing, target-name " "aliasing, etc." ] }, ... ], "count": N } On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Columns + curated enums/notes + a sample of rows for one table, in one call. Returns the real column list (name + datatype), curated `value_enums`, `notes`, and `sample_rows` (best-effort — `sample_status` ∈ {ok, error, disabled}). Reliable metadata is always returned even if the sample fails (some archives reject unfiltered reads). Soft-fails (`known: false` + hint) when the table/archive can't be identified. Note `known` means "has curated schema knowledge" (same convention as describe_table), NOT "table identified" — for a known archive/endpoint the column list is still returned even when `known` is false. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Resolve an object name to RA/Dec (ICRS, decimal degrees). Returns ``ra`` and ``dec`` suitable for ``CONTAINS(POINT('ICRS',ra,dec), CIRCLE('ICRS',<ra>,<dec>,<radius>))=1`` ADQL predicates or as the positional input to ``search_catalog_by_position``. On miss returns ``{"resolved": false, ...}`` — try an alternate designation or use ``search_ivoa_registry`` to locate a catalog by keyword. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Run an ADQL query against any IVOA-compliant TAP service. BEFORE composing a query against an archive you don't already know cold, call `list_archives` first. It returns curated usage notes for the well-known archives — non-standard table locations, required mode='async' routing, ADQL quirks, target-name conventions — that will save you trial-and-error here. The server never holds result bytes. Small results come back inline; anything larger than the inline cap is routed to an async job whose result the client fetches itself (see get_async_job_results / fetch_recipe). Returns one of two envelope shapes depending on what happened: 1. Inline result envelope (row_count, columns, rows). Returned when the result fits the inline cap: mode='sync' with a small result, or mode='auto' when the query finished within the sync timeout AND fit inline. No `mode` key on the response. 2. Promotion envelope (mode='async', job_url, fetch_recipe). Returned when mode='async', when mode='auto' and the sync attempt timed out, or when mode='auto' and the sync result was too large to inline. Disambiguate by checking payload.get('mode') == 'async'. mode='sync' with an oversize result does NOT auto-promote — it raises validation_error telling you to re-run with mode='async'. For async results, poll get_async_job_status(job_url) until phase is COMPLETED, then call get_async_job_results(job_url) — or fetch client-side with the pyvo fetch_recipe carried on the promotion envelope. Pass the job_url back verbatim; it is the job's only handle. Successful result envelopes also carry `query_fingerprint` and a `save_recipe` — after loading the result, execute save_recipe.code client-side to persist a CSV + manna_cache/catalog.csv row so the query need not be re-run later. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on —…

Run a Simple Cone Search (SCS) against a catalog endpoint. Returns the inline tabular envelope, same shape as run_adql_query. For most uses, prefer run_adql_query — SCS is here for catalogs that only expose the legacy protocol. Successful envelopes carry `query_fingerprint` + `save_recipe`; execute save_recipe.code client-side to persist the result and its catalog row. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Discover images at a sky position via Simple Image Access (SIA 2.0 or 1.0). Returns the inline tabular envelope. Each row is image metadata; the `access_url` column points at the image (a FITS file, or a cutout-service URL for archives like Data Lab). The server does not download images — fetch an access_url client-side (e.g. astropy.io.fits.open(access_url)). Most archives speak SIA2; NOIRLab Data Lab speaks SIA1. With the default version='auto' you don't need to know which — SIA2 is tried first and SIA1 is used as a fallback. For all-sky discovery first, see search_ivoa_registry with servicetype='sia'. Successful envelopes carry `query_fingerprint` + `save_recipe`; execute save_recipe.code client-side to persist the result and its catalog row. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Discover IVOA-registered services matching the given constraints. Returns a {services: [...], row_count, truncated, truncation_reason} envelope. Each service entry has: ivoid, title, description, publisher, waveband, and one URL per capability (tap_url, sia_url, scs_url, ssa_url; null when the service doesn't expose that capability). Use for discovery before calling run_adql_query / search_images_by_position / search_catalog_by_position on a specific endpoint. Smaller default maxrec (50) than catalog tools — discovery is about choice, not bulk data. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.

Survey which archives hold data for a target, with per-archive counts. Resolves the target, then runs each countable archive's curated positional COUNT and returns one row per archive: {archive, display_name, waveband, table, count, status, [job_url, next_steps]}. `status` ∈ {ok, pending, error} is always explicit — never a silent zero. A `summary` block totals archives_with_data / wavebands / pending / errors. Soft-fails (no error_class) on an unresolvable target. For a single archive with finer control, drop to count_observations_near_target or run_adql_query. On error, returns a Tool Execution Error payload with `error_class`, `message`, `retry_strategy`, and (when available) `hint`. The presence of `error_class` is the discriminator the LLM should branch on — do NOT rely on a separate `isError` field.