slowave

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

With no annotations, the description carries the full behavioral burden and does disclose non-obvious traits: a server-side session side effect, bounded/non-exhaustive retrieval ('not a complete inventory or a verification of the returned claims'), catalog truncation, cold_start vs available states, and stable warnings. It does not state permissions, auth requirements, or rate limits, which keeps it short of a 5.

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?

Well front-loaded and organized into purpose / cycle / args / returns, but substantially oversized: a long tail of agent-policy prose ('a user message establishing or changing durable guidance is also a task...') plus a full restatement of the cognitive cycle that repeats sibling-tool duties in prose. Several sentences could be trimmed without losing callable information.

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?

An output schema exists, so the detailed Returns block is arguably redundant, but the annotation-free status means the behavioral disclosure is necessary and is largely present for a multi-step memory system. The one genuine hole is semantic_context, absent from both description and schema.

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 only 43% across 7 params, so the description must compensate, and it does: the Args block adds real meaning beyond the schema for task ('copy verbatim, put interpretation in initial_goal'), continuity_id ('never invent it or reuse it across different client conversations'), and page_size bounds. It only misses semantic_context, which is undocumented in both places.

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?

Opens with a specific verb+resource ('Prime working memory with relevant context. Opens an implicit session.') and immediately states its role as step 1 of a named cycle. Siblings slowave_recall/remember/feedback/commit are placed explicitly in that cycle, so an agent can distinguish this entry-point tool from the mid-task and closing tools without opening any schema.

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?

Gives an explicit when ('Call this once at the beginning of every task'), an explicit alternative it removes ('you never need to call session_start manually'), and conditional guidance for downstream tools ('Recall only when needed history or details are absent'). It also resolves an ambiguous case (guidance-only and answer-only tasks still count as tasks). Nothing is left to inference.

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

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

No annotations are provided, so the description must carry the full behavioral burden, and it does substantively: it discloses the memory-consolidation side effect, the idle-reaper timeout with default, lifecycle-entry filtering during trajectory capture, and non-idempotent-looking-but-tolerated re-commit behavior ('operation: closed for a new close or updated for an already-ended session'). It stops short of stating permission/auth requirements or whether closing is irreversible, which is why this is a 4 rather than a 5.

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?

Front-loaded with the core action and the pre-call decision rule, then a structured Args list. It is long, and the Returns block largely restates fields already carried by the output schema, which is wasted space, but the prose itself is dense and each guidance sentence about the remember-vs-commit decision 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?

Given 7 parameters, 5 required, nested verification/procedure objects and 0% schema description coverage, the description supplies the missing semantics for every required and optional field plus omission guidance ('If you have no task-level actions, omit the trajectory'). The output schema covers return values, so the description need not explain them further.

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 has to compensate, and the Args block does: it labels session_id as the active session from activate, final_goal as the *confirmed* goal, explains outcome_summary as a 'standalone actual result', and details verification's status enum and procedure/trajectory content rules. The trajectory constraint (task-level only, max 32, no lifecycle bookkeeping) is genuinely additive beyond the schema.

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?

Opens with a specific verb+resource: 'Close the current task and trigger offline memory consolidation.' It also distinguishes itself from the sibling slowave_remember by stating what commit does *not* store (explicit claims). An agent can identify this as the terminal/close operation without opening the schema.

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?

Gives explicit when-to-use ('Call at the end of every task'), a when-to-use-alternative rule (store reusable knowledge with slowave_remember first, commit if nothing qualifies), and a when-not consequence (the idle-session reaper closes after SLOWAVE_SESSION_IDLE_TIMEOUT). It even handles the edge case of an already-ended session via the `operation`/`already_ended` semantics.

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

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

With no annotations, the description carries the entire burden and does so: append-only semantics, decoupled usage/relevance axes, neutral not_used/unassessable observations, and non-obvious server behavior ('Outer ok=true can contain rejected targets or failed batch items: inspect every results[i].ok, data.rejected and data.outstanding'). It also warns that 'A rejected complete request reports partial' and that 'silence under partial is not negative.'

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?

Front-loaded with purpose and the commit boundary, and most sentences carry operational rules that cannot be inferred elsewhere. It is dense and occasionally repetitive (the reason-required rule is restated for memory vs. procedure contexts), and the running-prose layout makes the many constraints harder to scan than they need to be, but little is pure filler.

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?

An output schema exists and the Returns section already enumerates every response field, so the description is free to spend its words on the hard parts: assessment semantics, batching, rejection recovery, and coverage semantics. An agent has everything needed to shape a valid call and to react to partial rejection.

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?

Top-level schema coverage is only 14%, but the description compensates by explaining nearly every field: scalar feedback vs. items mutual exclusivity, coverage default of partial, batch coverage placement, stale_reason values with the superseded/replacement_memory_id dependency, and procedure use-vs-effect separation. Minor gap: retrieval_quality and missing are described only in one vague clause each, with no expected format.

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?

Opens with a specific verb+resource: 'Record append-only evidence about retrieved memories and procedures.' It also explicitly fences off the sibling: 'Task outcome does not belong here; slowave_commit owns it,' so an agent can distinguish this from slowave_commit without reading either schema.

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?

Gives explicit when-to-report rules for each assessment ('Report used only after observed influence on reasoning, an action, a check, or an applied constraint; reading or topical similarity is insufficient'), sequencing guidance ('Complete all exposed targets after the relevant work, before commit'), and an exclusion ('Only returned targets need feedback; do not exhaust continuation pages'). Alternatives and edge conditions are covered, not left to inference.

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

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

With no annotations, the description carries the full burden and does so well: it discloses session/scope binding, that results are 'bounded suggestions, not proof of truth', that an empty result does not prove absence, that evidence can be truncated, and that continuations replay a frozen tail. It omits any note on auth requirements or rate limits, but the behavioral profile for a read-lookup tool is otherwise thorough.

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 purpose is front-loaded and the guidance is useful, but the long enumerated Returns block duplicates an output schema that already exists, making the description noticeably bloated. The query-crafting advice earns its place; the return-field catalogue largely does not.

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 an 8-parameter, session-bound retrieval tool with a separate output schema, the description covers usage, query construction, evidence modes, pagination/continuation and failure interpretation. The only real omission is the undocumented semantic_context parameter.

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 largely does, documenting the semantics and interactions of query, scope, session_id, task_context, evidence, continue_from and page_size (including the 'omit when continuing' rule). The one gap is semantic_context, which exists in the schema but is never mentioned in the Args section.

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?

States a specific verb and resource ('Semantic retrieval: bring relevant memories into working memory') and immediately scopes it against a sibling ('beyond what activate surfaced'). An agent can distinguish it from slowave_activate without opening any schema.

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?

Explicitly names the trigger ('deliberate mid-task lookups' needing 'specific historical context beyond what activate surfaced') and gives strong query-crafting guidance with a worked example. It does not explicitly say when NOT to use it versus slowave_remember/feedback/commit, so it stops short of a full routing rule set.

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

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses duplicate matching ('a matched claim is acceptable'), that writes can resolve to created or matched, and that occurred_at is a source-event time that never changes internal event ordering because Slowave stamps ts itself. It does not discuss permissions, failure modes, or rate/volume limits.

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?

It is front-loaded with the purpose and invocation trigger, then args and returns, so an agent can stop reading early. It is nonetheless roughly four times a typical description and repeats the standalone-claim guidance in two places, but nearly every sentence carries operational content rather than filler.

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?

Given a 6-parameter schema with 17% coverage, a nested entry shape, an output schema, and no annotations, the definition still covers invocation trigger, exclusions, both scalar and batch forms, per-argument semantics, and return fields (stored, memory_id, disposition, source_event_id, batch envelopes). Nothing an agent needs to call it correctly is missing.

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 only 17%, so the description has to compensate, and it does: scope must match the active session, session_id must be an active session from slowave_activate, content is one standalone claim mutually exclusive with memories, memories is a strict batch inheriting outer scope/session, type is explained with the instruction/procedure distinction, and occurred_at gets an RFC 3339 example plus ordering semantics. This is meaningfully richer than the schema.

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 first sentence gives a specific verb and resource with scope: 'Record newly discovered knowledge worth retaining for future tasks in this scope.' It is unmistakably a write/memory-persistence tool and contrasts implicitly with recall/activate/commit by describing when to save rather than fetch. It stops short of naming a sibling as the alternative, so it is clear but not explicitly differentiated.

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?

It gives an explicit invocation condition ('Proactively call this when you discover new knowledge... pursue a goal, avoid rework or a wrong assumption'), an explicit anti-pattern ('Do not wait for the user to say remember'), a positive candidate list, and a negative list ('Skip speculation, progress notes, pending steps, temporary task state'). It also states a prerequisite: the session and scope must come from slowave_activate.

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