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

With zero annotations, the description carries the full burden and does so: it discloses the server-side default action="write", asynchronous salience-aware extraction, 60-minute claim leases, CAS conflict return shape ({status:"conflict", claimed:false, current_agent_role}), first-verifier-wins attestation semantics, and the unsolicited 'perception' push-signal field with required agent responses. It also warns that unrecorded actions are lost across sessions, a real persistence consequence.

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

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

The description is long but front-loaded with the single most important instruction (one content string, call after every action) and organized under clear headers with runnable examples. The per-signal 'YOU MUST ACT' playbook is arguably over-specified, but given a 21-parameter unannotated tool, most content earns its place.

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

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

For a 21-parameter tool with no annotations and no output schema, the description covers the write path thoroughly and sketches response behavior (conflict objects, perception field). But it leaves the eleven remaining parameters unexplained and never addresses authentication (api_key), multi-tenant scoping (user_id/actor), retention/pagination (max_events), or the response shape for the plain write path.

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

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

Schema description coverage is 0%, so the description must compensate, and it does well for roughly half the surface: action, content (with type-detection rules for str vs list vs scope="knowledge"), insights shape, scope, session_id, task_id, status (including legacy pending/in_progress/completed aliases), expect_status, handoff, and verified_by. However, 11 of 21 parameters — actor, source, api_key, user_id, metadata, memory_id, agent_role, event_type, max_events, generate_summary, metadata_defaults — are never explained, leaving a substantial semantic gap.

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

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

The opening line states a specific verb and resource — 'Save memory — pass ONE content string, server handles the rest' — which immediately distinguishes it from read-oriented siblings like awareness_timeline, awareness_recall, and awareness_search_knowledge. The description then adds a second mode (action="update_task") for task state transitions, which muddies the single-purpose name somewhat, though the mode split is explicitly labeled.

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

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

Explicit 'Call AFTER every meaningful action (code edit, decision, bug fix, discovery)' timing, plus a clear statement that action/scope/metadata should NOT be passed in the primary path. It separates 'OTHER ACTIONS (explicit — server will NOT infer these)' from the default write path and gives per-transition guidance (claim/renew/handoff/finish/attest) with the correct expect_status for each.

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