write_episode

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

With no annotations provided, the description carries the full burden and meets it thoroughly. It discloses that the server never calls an LLM and that the calling agent must extract entities/facts itself, specifies that the confidence value must be exactly one of three literal strings or the call is rejected, and explains when entity_resolutions is required. It also documents the strict matching constraint between fact source/target and entity names, giving the agent a clear behavioral model.

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: it front-loads the purpose, gives precise field-by-field shapes and validation rules, and ends with a concrete example. Given that the schema provides no property descriptions, the length is justified and well-structured rather than verbose.

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 5-parameter tool with no annotations, no output schema, and an empty schema, the description covers the entities/facts structure, confidence validation, optional entity_resolutions flow, and an example. It falls short on the semantics of scope and session_id, and it does not describe what the tool returns in response, so an agent still has some uncertainty about the complete call contract.

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?

The input schema is nearly empty (objects with additionalProperties: true and 0% description coverage), so the description must compensate. It richly defines entities (name, type, uniqueness), facts (source/target/relation_type/fact/confidence with validation), and entity_resolutions (resolved_to or new). However, the two required parameters scope and session_id are only shown in the example call and never semantically defined, leaving a gap in compensation.

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 clearly states a specific verb and resource: 'Record something worth remembering later' and enumerates concrete examples (a decision, a correction, a stated preference, or context). It does not explicitly contrast itself with the sibling tool 'record_recall_save', so an agent cannot immediately distinguish between the two write-like tools, which prevents a 5.

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 description gives explicit situational triggers: 'Call this proactively and immediately when you notice one of these - don't wait to be asked, and don't batch it up for later in the conversation.' It also explains the cost-benefit rationale for erring on the side of calling. However, it does not mention any alternatives or state when not to use the tool, so it lacks exclusions and sibling routing.

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