memory_verify

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

With no annotations, the description carries the full burden and excels: it discloses idempotency, REPLACE-not-append list semantics, refusal conditions for absent paths and false claims, the stale status when another agent verifies first, and the side effect of resolving a `record_use(contradicted)` flag. These are meaningful behavioral details beyond what the schema provides.

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 every sentence earns its place given the tool's subtle semantics. It front-loads the core purpose and side effect, uses paragraph breaks and bullet-style parameter explanations, and avoids irrelevant 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?

Despite having no annotations and seven parameters, the description is complete: it covers parameter semantics, refusal behavior, idempotency, interaction with memory_update, stale-status responses, and a health-flag side effect. The output schema exists, so return-value detail is not required, but the description adds extra return context with status='stale' and the hint to re-fetch.

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 does. It explains every parameter's role: `verified_paths` as the only attestation read by drift legs, `verified_commits`/`verified_versions` as audit-only, `verified_absent_paths` as intentional absence, and `claims` as memory_write-compatible syntax. It also clarifies `None` vs `[]` vs populated list 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?

The description opens with a specific verb and resource: 'Bump `last_verified_at` to now after spot-checking that a memory's claims still match reality.' It clearly distinguishes memory_verify from memory_update by explaining that verifying does not bump `updated`, while memory_update does not bump `last_verified_at`.

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?

Provides explicit when-to-use and when-not-to-use guidance: use after spot-checking, use verified_paths when the memory cites paths, never use verified_absent_paths for real drift, and re-verify after memory_update because it clears last_verified_at. It also names the sibling alternative memory_update, making the boundary unambiguous.

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