Skip to main content
Reads durable structured records of one configured record type.

​
Authentication and enablement

This native tool is off by default. Add it as a configured tool on an agent and select:
  • a workspace Data Store record type
  • agent scope for records shared across that logical agent’s task runs and versions, or workspace scope for records shared with other explicitly configured agents
  • whether the tool may return fields marked sensitive
Record type, scope, and sensitive-read access are configuration-only values. The agent cannot change them in a tool call. Workspace identity and logical-agent identity come from the execution context.

​
Inputs

  • operation (required): get, readiness, or list
  • key: exact record key returned by an earlier update or list result; required for get and readiness
  • filters: top-level equality filters for list; only fields marked filterable in the record-type contract are accepted
  • limit: list result limit, default 20 and maximum 100
Sensitive fields and object/array fields cannot be filterable; equality filters are limited to string, number, and boolean fields. For contracts with multiple identity fields, or one non-string identity field, the generated key is an opaque sha256: value. Save the key returned by update_data_store; when it is unavailable in a later task, use list to find the record and recover its key before calling get or readiness.

​
Output

get returns record with its key, JSON value, version, updated_at, ready, and missing_required_fields. readiness returns only readiness metadata, including updated_at but not the stored value, and reports whether additional missing required fields are hidden because they are sensitive. List returns records (each including updated_at) and count. Sensitive values are replaced with [REDACTED] unless sensitive-read access is enabled. Sensitive fields that are missing are omitted from missing_required_fields, and sensitive fields explicitly set to null remain null. version increases after each successful write and can be passed to update_data_store as expected_version for an optimistic-concurrency check. updated_at lets callers assess record freshness without reading administrative APIs.

​
Limits and side effects

The tool is read-only. Records persist until their record type or workspace is deleted; v1 has no per-record deletion or retention timer. The tool does not support joins, aggregation, nested JSONPath, semantic search, full-text search, or fuzzy matching.

​
Expected errors

  • record type or record not found
  • base tool enabled without first creating a configured instance
  • key missing for an exact operation
  • filter field is not declared filterable or has the wrong configured type
  • configured scope is invalid or agent execution identity is unavailable
  • database operation failed