Archive or restore memories

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

Goes well beyond the annotations: it names the underlying operation (POST /api/memory/bulk), the required scopes (memory:write, luca:draft), the redacted data sensitivity, and the Idempotency-Key requirement including server-side generation. The 'always reversible' framing mildly softens destructiveHint=true, but it reads as an accurate domain explanation of what 'destructive' means for archiving rather than a contradiction, since the tool exposes a restore action.

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 purpose and the reversibility guarantee, followed by compact operational metadata (endpoint, scopes, idempotency, workspace override). The 'Required scopes' / 'Required OAuth scope' lines are slightly redundant with each other but each carries a distinct auth fact.

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 bulk mutation with a nested body, an output schema, and strong annotations, the description supplies the auth, idempotency, and reversibility context an agent needs. The main remaining gap is partial-failure behavior when only some of up to 100 ids fail, which affects retry strategy.

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 coverage is 75%, so the body/action/ids parameters are already documented structurally. The description adds real meaning for workspaceId/workspaceSlug (they override the environment-configured default workspace) but restates the idempotencyKey behavior almost verbatim from the schema, and says nothing about the 100-id batch ceiling or the archive/restore enum semantics.

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 pair and resource ('Archive or restore several memories at once'), with the bulk/plural scope making it distinguishable from the singular luca_memory_update and the read-only luca_memory_list. It never names those siblings explicitly, so differentiation is inferred rather than stated.

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?

The sentence 'Archiving stops Luca using a fact while the record and its provenance survive' implies when archiving is appropriate (suppressing a fact rather than deleting it), but there is no explicit when-to-use/when-not or pointer to luca_memory_update for single-record edits. Usage is inferable but not directed.

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