profile_mark_learned

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

With no annotations, the description carries the full load: it discloses the write intent, the memory's purpose, and the dedupe effect on future explanations. It does not say what happens if a topic is recorded twice, whether entries are scoped per conversation/profile, or what the call returns.

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?

A single front-loaded sentence: the memory label and trigger come first, the recording instruction second, the rationale last. No redundant wording and nothing that repeats the schema.

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 one-parameter, non-destructive memory append with no output schema, the definition covers trigger, content, granularity, and payoff. Only edge-case behavior on duplicate topics is left implicit, which is minor for this complexity.

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 100%, so baseline is 3, and the description adds real meaning beyond it: topics must be short names, with concrete granularity examples ('pantheon', 'more vs increased', 'cluster jewels') that show the expected abstraction level rather than full sentences.

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 (record) and resource (topic) plus the scope that makes it distinct: 'Teach mode memory' for PoE1 mechanics the agent has just explained. This clearly separates it from the generic profile_get/profile_set pair without needing to name them.

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 trigger condition — 'after explaining a PoE1 mechanic to the player' — which is exactly the moment an agent needs to decide to call it. It states the downstream benefit ('so it isn't explained again') but does not explicitly rule out or point to any alternative tool.

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