remember

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

With no annotations supplied, the description carries the full behavioral burden: it discloses the one-fact-per-call constraint and that the agent should surface the save to the user in one line, which is useful. It says nothing about persistence scope, deduplication of existing facts, overwrite behavior, or whether a stored fact can later be edited, which matters for a memory-write tool.

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?

Two short sentences with no filler, and the core action is front-loaded before the user-notification instruction. "Tell them in one line" is slightly terse but still actionable.

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?

The tool is simple (two params, no output schema, no annotations), so it doesn't need much, and the description covers the payload shape adequately. The unresolved gap is category selection, which is the single decision an agent must make and is entirely unexplained.

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 50%: the fact parameter is documented ("One short, specific sentence"), but the category parameter has six enum values (workflow, communication, code, decisions, learning, tone) with no description anywhere. The description never mentions categories at all, so the one genuinely ambiguous field is left to guesswork.

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?

"Save one preference, habit or correction about your human" gives a specific verb (save) and a specific resource (a durable fact about the user), and the cardinality constraint ("one") is stated. It is distinguishable in practice from forget and get_profile by its write semantics, though it never names an alternative explicitly.

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 scope (preferences, habits, corrections) implies when to call it, but there is no explicit trigger, no when-not guidance, and no pointer to sibling tools such as forget for removal or get_profile for reading back. The agent must infer the usage context from the resource description alone.

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