record_decision

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

No annotations, so the description carries the full burden. It usefully discloses the effect (persist across sessions) and the write target, but it does not say whether an existing decision is overwritten, what permissions are needed, or what the response looks like; it also conflicts with the schema's claim that the value is written to AGENTS.md rather than docs/mcp-learnings.json.

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?

Compact and front-loaded: what is recorded comes first, followed by constraints and the write target. No filler, though the closing file reference adds a contradiction rather than clarity.

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?

With no annotations and no output schema, the description must cover behavior on its own. It covers purpose, trigger discipline, and persistence, but leaves overwrite/merge semantics and the full decision set unaddressed and introduces a destination inconsistency an agent cannot resolve.

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 100%, so the baseline is 3. The description only restates part of the 'decision' enum (authorization) and the value set, omitting 'postman', and its stated output location contradicts the schema's per-parameter notes.

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?

Specific verb+resource: records an explicit user decision that applies repo-wide so it isn't asked again next session, and names the storage file. The scope is clear, though it only enumerates 'authorization' while the schema also allows 'postman', leaving the full purpose slightly under-stated.

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 when-to-use (a decision already made that must persist) and a firm when-not ('solo con una respuesta clara del usuario; nunca por suposicion del agente'). It does not name alternatives such as record_architecture, so routing between the two record_* siblings is left to inference.

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