Route first, query second. Select sources by entity type, organism, identifier namespace, evidence
model, and release. The resource tool progressively exposes database metadata and instructions;
the Agent determines the task-specific execution from each loaded package.
-
Record the requested entity, organism, namespace, evidence type, freshness requirement, and any
named database. A named database selects that source; an unnamed database-dependent set request
selects every scientifically applicable package returning the requested entity type. This step
is complete when the source inclusion and exclusion rules are explicit.
-
Browse the relevant domain with resource({ action: "list", category: "<selected-category-path>" }). When the response has kind: "categories", choose an exact
child path and list it; repeat until the response has kind: "resource_metadata". Category
entries are navigation choices, while resource_metadata entries are selectable packages.
This step is complete when every branch matching the inclusion rules from step 1 has reached
resource_metadata and every returned candidate has been compared by scientific scope,
organism, entity type, and access mode.
-
Load only the selected package instructions using the exact name copied from its leaf
metadata:
resource({ action: "read", name: "<exact-resource-name>" })
Treat the loaded RESOURCE.md as the authoritative access contract. Follow its reference
routing before data access: read the named schema or interpretation reference when the requested
result depends on entity filtering, member counting, identifier mapping, pagination, or endpoint
semantics. Inspect a bundled script's --help or source only when the package documentation does
not state the required invocation. Use the loaded package contract as the source of
database-specific access instructions.
This step is complete when each selected package's query interface, response schema, identifier
semantics, version behavior, required references, and path conventions are known well enough to
define the intended result before querying.
-
Build a retrieval ledger with one row per selected package: exact package name, discovery
operation when an ID is unknown, complete retrieval operation, documented output schema, and
intended raw artifact. Execute each package according to its loaded access contract. Use live
services for remote and bundled snapshots for local.
For hybrid, apply the package's local coverage gate before any network call. Local coverage is
sufficient only when the available data—not merely documentation or a client script—matches the
requested operation, entity, organism, identifier namespace, release requirement, and complete
membership or fields. Use that local result alone when the gate passes. Escalate only the
uncovered request to the documented remote service when the gate fails, the local result is a
valid empty result, or the user requires current/live data or independent remote validation.
Record the gate decision and fallback reason; keep local and remote evidence separate when both
were explicitly required.
Give each selected record one complete retrieval. Use a separate discovery request only when
the exact record ID is unknown. Prefer a package's structured output option and treat its
documented schema as the contract. Let one workspace consolidation script be the first consumer
of completed raw outputs: read every selected output once, perform task-specific filtering and
mapping, and write all derived source artifacts and provenance in one run. Then validate all
output schemas, array lengths, hashes, and reported counts in one pass. Additional inspection is
reserved for a failed documented-schema check, changed parameters, pagination, recovery, or an
independent validation request.
This step is complete when every ledger row has one result, a valid empty result, or a concrete
failure, and every successful row points to its raw and derived artifacts.
-
Pass the runtime Artifact report gate. Preserve complete results in canonical workspace
artifacts, then report every source independently with its database, query or record, organism,
namespace, release or retrieval date, access mode, exact result count, and artifact path.
Perform merging or identifier mapping only when requested.
This step is complete when all selected sources and returned members are accounted for in the
artifacts; every reported identifier is present in a documented artifact field; every reported
count is computed from an artifact field; and complete membership lists remain in deterministic
artifacts rather than model-composed prose.
Interpret an empty response as version-specific evidence. Use package directories as read-only
sources and write all generated output to the Session workspace.
