Update to Sugra API

Changed files

Choose a file to see its text changes. Binary or large files show metadata only.

.app.json →

.codex-plugin/plugin.json →

assets/logo.png →

mcp.json →

plugin.json →

skills/auth-and-quota/SKILL.md →

skills/auth-and-quota/agents/openai.yaml →

skills/cross-domain-briefing/SKILL.md →

skills/cross-domain-briefing/agents/openai.yaml →

skills/discover-and-call/SKILL.md →

skills/discover-and-call/agents/openai.yaml →

skills/envelope-and-attribution/SKILL.md →

skills/envelope-and-attribution/agents/openai.yaml →

skills/live-docs/SKILL.md →

skills/live-docs/agents/openai.yaml →

skills/using-sugra-api/SKILL.md →

skills/using-sugra-api/agents/openai.yaml →

skills/discover-and-call/SKILL.md

− removed · + added

--- before
+++ after
@@ -0,0 +1,60 @@
+---
+name: discover-and-call
+description: Find the right Sugra operation, call it over HTTPS or MCP, and check that the result answers the question. Use when the path or operation_id is unknown, before guessing parameters, before quoting a figure, or after a catalog miss. Confirm details on https://docs.sugra.ai. Do not invent routes.
+license: MIT
+---
+
+# Discover and call
+
+Do not invent paths or `operation_id`s. Confirm the operation on https://docs.sugra.ai (search or Ask AI, then the endpoint page). Two complete loops, same API.
+
+## HTTP loop
+
+1. If the path is already known, skip to step 4 after confirming it on docs.sugra.ai.
+2. Search https://docs.sugra.ai. Machine companion: `GET https://sugra.ai/openapi.json`. List of source names: `GET https://sugra.ai/sources`.
+3. Read every parameter with its default and, for POST, the request body. Parameter names come from docs or the spec, spelled exactly: over HTTP most routes ignore an unknown query parameter without an error, so a misspelled filter (`country` for `countries`) returns the default data.
+4. Call `https://sugra.ai` with `x-api-key`. Set every parameter the question names (place, identifier, period, frequency, unit). GET uses query params. POST uses JSON body plus any path or query params the spec lists.
+5. Parse `{data, meta}`, or the flat object with `meta` / `_meta` that a few payloads return. Check the answer (below), then cite the source and the figure's date (check 4). Read `X-RateLimit-Remaining`.
+
+```
+GET https://sugra.ai/api/v1/etf/sectors/relative-strength?window=1m
+x-api-key: sugra_...
+```
+
+## MCP loop
+
+Works on hosted and stdio. Do not call hosted-only names on stdio. The catalog tools (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) read the catalog bundled with the server and do not call https://sugra.ai; only `call_endpoint`, `fetch_data`, and the entity tools do.
+
+1. `search_endpoints(query=..., toolset=None, source=None, limit=10)`. Unknown `toolset` / `source` returns `unknown_toolset` / `unknown_source` with the valid set, not an empty hit list.
+2. Pick an `operation_id` from `results` by its summary, not by its rank: the first hit is not always the measure asked for (a search for an unemployment rate can rank a labour force participation series first). Confirm it on docs.sugra.ai.
+3. `describe_endpoint(operation_id=...)` - params with defaults, `request_body_schema` on POST, `agent_hints` (`duration_class`, `max_concurrency`, `bulk_cost`).
+4. `call_endpoint(operation_id=..., params={...}, body=...)`. Set every parameter the question names. On the hosted server a key the operation does not declare returns `unknown_parameters` with `accepted` and, when close, `did_you_mean`.
+
+`fetch_data(query=...)` is a one-shot: it calls the top catalog match with the params given. A missing required parameter returns `needs_params` with the selected endpoint and candidates; a missing optional one silently takes its default. Check the answer below before using it; if the operation or the place is wrong, use the four-step loop. `list_toolsets` and `list_sources` (resources `sugra://catalog/domains`, `sugra://catalog/sources`) are the map, not the query.
+
+Shaping on `call_endpoint` / `fetch_data` (`limit`, `fields` as dotted paths, `include_raw`): skill `envelope-and-attribution`.
+
+Hosted only: `resolve_entity`, `get_snapshot`, `get_timeseries`. LEI/VAT and sanctions on every transport: `sugra_entity_lookup`, `sugra_entity_screen`.
+
+The MCP prompts (`market_snapshot`, `macro_briefing`, `sanctions_screening`, `sector_compare`, `earth_conditions`, `source_overview`) are numbered recipes over the gateway tools. They are not the catalog and do not cover every direction. For anything they do not name, use the loop above.
+
+## Check the answer before quoting it
+
+1. `meta.endpoint` is the operation you meant.
+2. The place, entity, and period in `data` are the ones asked about, not a default.
+3. The measure is the one asked about: a participation rate is not an unemployment rate, a level is not a change, a monthly figure is not an annual one.
+4. The figure is dated by an `as_of` (in a record, in `data`, or in `meta`), by `meta.period`, or by a `data_time` the source stated, never by one that fell back to the response time. With none of them, say the source time is unavailable (skill `envelope-and-attribution`).
+
+If any check fails, fix the call. Do not present a near miss as the answer, and do not fill a gap from memory.
+
+## Misses and errors
+
+A miss is not "Sugra has no data". Search docs.sugra.ai. Widen the query. Drop a bad MCP `toolset`/`source` filter. If MCP search still misses, fetch live `/openapi.json` (the wheel catalog can lag), then HTTP-call if the spec has it.
+
+An error message usually names the fix: read it before retrying. A 400 or 422 over HTTPS names the parameter or value to change; over MCP a 422 can arrive as a bare `HTTP 422`. Full table: skill `auth-and-quota`.
+
+Do not add per-endpoint MCP tools to skip this loop. Do not skip `describe_endpoint` when the parameter list is unknown.
+
+## Timeouts
+
+30 seconds covers most GETs. Bulk or live-upstream POSTs can run longer. MCP `agent_hints.duration_class` is the budget hint. A timeout is not empty data.