Skip to main content
Glama
aoci-spec

aoci-code

by aoci-spec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

aoci_maintain

Retrieve the next complete machine-issued authoring batch once managed content is stable, resolve repair or stopped states, and return bounded candidates for atomic review updates.

Instructions

After managed content reaches its final stable state, obtain the next complete machine-issued authoring batch. Legacy behavior remains compatible: provable format-only drift may advance the Baseline, and local Ledger audit records may be appended. Resolve repair_required or stopped completely. Do not call again for a purely read-only task, an unstable intermediate state, or an already aligned repository. When refresh is pending, Verify, Check, and Guide must prove aligned first. A new repository or incomplete index must use the current Guide; this tool cannot replace that workflow. In Volumes v1, omit scope on the ordinary path: shared governance facts determine aligned, authoring_required, evidence_required, or blocked. For a large logical plan, Maintain deterministically returns at most max_entries candidates, cut by the team transport budget maintain_transport_budget_bytes (default 24 KiB) under the team cap code_cognition_batch_entries (default 50, ceiling 200), with logical_plan, batch_identity, total_targets, included, remaining, continuation_required, Composite/Scope identity, per-target source or Evidence bindings, and the exact Guide action. For Code, copy code_plan.batch_id to aoci_update_entry.code_batch_id; it equals every returned Code candidate.batch_id. authoring_batch.batch_identity identifies the cross-domain authoring envelope and is not a Code or Database write batch id. This is the complete candidate set for the current batch, not an arbitrary prefix the Host may change and not a Whole-Index limit. Apply it atomically; if remaining is nonzero, call Maintain again against the new preimage. Whole-Index aligned is allowed only when remaining, missing, stale, unbaselined, orphan, Scope debt, and Recovery are all clear. Maintain may write only machine candidate receipts and local Ledger audit records; it never authors tag or F/R/A/S, connects to a database, changes Scope, or reduces Index coverage for transport limits. Orphans remain explicit remove candidates, Root and Meta remain guards, and explicit scope=database only reads saved Canonical Evidence, contains no program-generated tag or FRAS field, returns database_volume_absent when the Database Volume is absent, and creates no Root, Meta, or Database Volume. An explicit Cognition Optimization request is the sole aligned-Entry exception: only for Volumes v1 Code, set intent=cognition_optimization and optionally object_refs to obtain bound review candidates. For every candidate, the Host reviews the current complete Entry, source, and necessary relations, then submits either a complete replacement Entry or the unchanged complete Entry through the existing aoci_update_entry batch; field patches are forbidden. AOCI selects and binds candidates only: it never generates semantics or S, compresses Entry text, or lowers C. This mode never applies to Legacy or Database cognition.

Input Schema

NameRequiredDescriptionDefault
scopeNoOptional advanced diagnostic scope. Omit it for ordinary Volumes v1 maintenance so AOCI automatically selects Code, Database, both, aligned, evidence_required, or blocked; explicit code, database, and all remain compatible
intentNoOptional explicit mode. cognition_optimization is supported only for aligned Volumes v1 Code Entries; when omitted, ordinary Maintain behavior is unchanged. AOCI only selects and binds review candidates and never generates semantics, compresses Entry text, creates S, or lowers C
object_refsNoOptional canonical Code object references in code:<repository-relative-path> form that limit cognition_optimization candidate discovery; valid only with intent=cognition_optimization and never interpreted as field patches

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden, and it does: it discloses write scope (machine candidate receipts and local audit records only), atomic application, continuation semantics (if remaining is nonzero, call again against the new preimage), and explicit prohibitions (never authors tags/FRAS, never connects to a database, never reduces Index coverage for transport limits). It also enumerates the return fields and batch identity rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the core purpose, but the body is a wall of dense, acronym-heavy prose that is hard to parse and would benefit from structured bullets. Much of the detail is necessary for this complex orchestration tool, but the presentation is not concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex orchestration tool with no output schema, the description explains return fields (logical_plan, batch_identity, included, remaining, continuation_required), transport limits, and the exact review/submit follow-up. It is nearly complete, though the lack of an output schema leaves some return-shape details implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful scope behavior beyond the schema: explicit scope=database only reads saved Canonical Evidence, contains no program-generated tag or FRAS field, returns database_volume_absent when the volume is absent, and creates no Root/Meta/Database Volume. It also reinforces the intent/object_refs binding constraints for cognition_optimization.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource: obtain the next complete machine-issued authoring batch after managed content stabilizes. That distinguishes it from aoci_update_entry, which submits entries. The remainder is dense with internal jargon (Baseline, Ledger, F/R/A/S), but the core action is identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when not to call (read-only task, unstable intermediate state, already aligned repository), names prerequisites (Verify/Check/Guide must prove aligned when refresh is pending), and routes new repositories to the Guide. It also distinguishes the ordinary path (omit scope) from the explicit cognition_optimization exception.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools