Skip to content

Personal tools and trusted account management

Registry v20 retains 67 executable personal tools alongside 51 financial/discovery entries. Existing financial names, input and result contracts remain supported. The public argus:tools:public whitelist covers everyday financial research. Advanced and diagnostic tools need explicit signed discovery grants plus data scopes. Explicit signed personal domain scopes and current owner consent are required for private reads/writes; they are never inherited from fact scopes. Search checks every requested domain. Confirmation preparation checks its target operation.

Consumer OAuth connections on /mcp list only the 20 consumer tools, which return consumer-result-v1. The tools on this page are neither listed nor callable there; use their CLI and REST bindings.

The executable catalog is argus.contracts.personal_tools.PERSONAL_TOOLS and is included in the authoritative registry, generated bindings, runtime OpenAPI, MCP schemas and release schema catalog. personal_operations and personal-contract-foundation.v1.json retain the earlier design/foundation and do not independently activate operations. Inspect the current registry to learn which operations are callable.

Requests and responses

REST and MCP use the same closed JSON request. Personal CLI commands use the registry's hyphenated command and --request-file FILE; the file contains that same request JSON. Authenticate using the existing OAuth login/secure credential store. Credentials and ownership are never arguments in personal JSON.

personal-result-v1 carries result_kind, request_id, audit_id, and exactly one of payload and problem. Payloads contain owner_id, lifecycle_id, domain and the operation's typed data. Families distinguish private objects, management, usage, tasks, confirmations and governed financial compositions. Financial compositions preserve the original child packages, evidence, clocks, source rights and audits. Saved queries execute through the canonical fact service again. User notes remain labeled untrusted user content and are never financial facts or platform recommendations.

A research note has an optional note_kind, note or question (a pinned question). personal_notes_create_v1 and personal_notes_update_v1 accept it, and an update that omits it keeps the stored kind. A note's record returns it, and so does the note's hit in personal_search_read_v1. Tags are the owner's own words and never decide the kind. A note stored before the field existed has none: its record leaves the field out, and its search hit reads question only when the note carries the question tag that marked it then.

The earlier six foundation result schemas remain available; clients use the per-tool output schema for the new business DTOs. Existing financial invocation responses retain CliToolEnvelope. HTTP authentication and schema failures may precede core entry. Personal validation responses exclude input values. MCP clients first check transport errors/isError and then decode the typed result.

The existing documentation site validates personal request schemas, saved-query definitions, confirmation target requests and filing selection completeness. Object, preview and confirmation identifiers refer to earlier steps under the user's authorization. Local demo credentials cannot execute private operations: the documentation harness checks refusal through REST, remote CLI and MCP. Authorized personal success is covered separately by the real PostgreSQL/Redis interface parity suite. Structural business-input validation does not establish owner access, source coverage or mutation success. The harness reuses its CLI command tree and MCP catalog while preserving each individual invocation and assertion.

Writes, retries and confirmation

Inspect the generated mutation_policy and MCP annotations. Ordinary CRUD keys bind owner, lifecycle, operation and input; edits/deletes use the current object version. A reused key with different input fails. Read acknowledgement sets read once. Preview creation, expiring download-reference issuance, preference version updates and confirmation preparation explicitly declare their distinct retry behavior; they are not advertised as unconditional idempotent writes.

Import commits bind the preview, selected rows, replacements and owner-approved confirmation. Deleting a list that affects subscriptions similarly binds all affected versions. Removing watchlist members needs a confirmation only when one call names more than 50 of them; up to 50 are removed directly. Preparing confirmation is permitted to the originating Agent; approval belongs to the trusted account session. An Agent-provided confirmed flag, owner identity, arbitrary sensitive operation or hidden tool cannot approve or perform account revocation, deletion or identity changes.

The owner may approve an ordinary bulk plan created for a configured API or MCP resource. Approval checks owner/lifecycle, active account, stored operation, versions and expiry under the account lock; it preserves the plan's original client, resource and digest. The consuming Agent must still match those bindings. Sensitive account confirmations remain bound to the trusted web management resource.

Downloads

personal_exports_download_v1 issues a private 300-second reference. POST it in the JSON body to /v1/personal/export-content, with an optional byte offset, using the same authenticated context. CLI also exposes personal-export-content --request-file FILE --output FILE; it requires a new output path and writes a bounded temporary file before atomic delivery. An offset produces the remaining bytes for an explicitly managed resume. Every emitted chunk rechecks the existing owner, grant, source, lifecycle and expiry rules. References are never URLs or object-store signed links. A stopped stream is incomplete; downloaded bytes cannot be recalled.

This byte-only endpoint verifies either the API or MCP resource's original credential. The download reference must still match that exact resource, client, session, owner and lifecycle; an API credential cannot consume an MCP-bound reference. Ordinary REST business endpoints continue to require the API resource. No audience exchange or broader business grant is implied.

Personal CLI discovery declares JSON-file arguments and credentials from the secure store or environment. MCP and REST accept the same closed JSON object. The existing binding maps reserve $request for the whole JSON file (parameter_encodings: json_file, parameter_aliases: request_file), preserving the v18 registry model's closed field set. All three transports allow the frozen 5 MiB CSV input, including bounded JSON escaping and protocol overhead; business file, row and storage limits are unchanged. Personal CLI requests refuse HTTP redirects so a bearer or private body cannot be forwarded to a different endpoint. Authentication failures, capacity refusals and business conflicts each produce one typed JSON result.

Trusted account API

The separate catalog release/personal-management.v1.json declares the /account/api/* operations. These require the existing secure web cookie, same-origin protection, cookie-bound CSRF and current terms. Sensitive operations also require account:trusted_management, recent server-verified owner proof and bound confirmation. Proofs are reused only within the same real session and original five-minute deadline. Owner operations use the independent 60/minute management window, not a financial-tool window. Request bodies and private results are excluded from audits.

Prepare and confirm revocations or domain consent using the same effect and confirmation identifier. consent-batch-prepare and consent-batch-confirm change up to 16 distinct consent rows of one client under one confirmation; the rows commit together, each with its own expected version. A changed effect/version is refused; a completed retry returns only its original receipt. Bulk approval is limited to an existing server-created import/list-deletion plan owned by the current account. Full export and deletion remain owner-only. Identity changes link to the configured identity provider, where verification occurs.

Deletion preparation returns the independent progress credential only in the private body. Save and actually query it with POST /account/api/deletion-progress before confirming. It continues after login is disabled, and cannot access other data or cancel deletion. The server stores only its irreversible verifier. Account APIs return no-store/no-referrer and do not accept credentials in query parameters.

These adapters also back the personal pages and trusted account flows of the Argus web app at /account/.

MCP HTTP calls use the authenticated identity attached to the current message, including nested financial calls. A long-lived protocol session cannot retain its opening scope or tool whitelist after the registered grant narrows.