Agent Memory Bridge

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

With no annotations, description must carry full burden. It successfully discloses idempotence (keeps same id) and mutation scope (updates in place). However, missing safety-critical details: reversibility (can it be demoted?), prerequisite states (must be unpromoted?), and side effects on the record's history/lineage.

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?

Three tightly-constructed sentences: definition (sentence 1), usage context (sentence 2), side effects (sentence 3). No redundancy, front-loaded with action, zero padding. Every clause 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?

Appropriate for a 2-parameter mutation tool with complete input schema and existing output schema. Covers purpose, usage trigger, and behavioral modification. Minor gap: lacks mention of error conditions (e.g., what if already promoted?) or prerequisite validation, though these may be in output 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?

Input schema has 100% description coverage with detailed enum explanations ('learn' for reusable claims, etc.). Description reinforces these semantics by repeating the three target types in the usage paragraph, but adds no syntax or format details beyond what the schema already provides. Baseline 3 appropriate for high-coverage 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?

Excellent specificity: 'promote' (verb) + 'stored memory' (resource) + 'to a stronger durable record type' (transformation). Explicitly distinguishes from automatic 'reflex layer' promotion and clarifies this is manual intervention.

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?

Contains explicit when-to-use clause ('when you know a record should be treated as... even if the reflex layer has not promoted it yet'), clearly contrasting manual vs automatic promotion. Lacks explicit 'when not to use' or named sibling alternatives (e.g., store for new records vs promote for existing).

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