layerwright_memory

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

No annotations are provided, so the description carries the full burden. It discloses a meaningful side effect: this writes to a shareable file (.layerwright/memory.json) shared with the team, and that saved notes persist into the next session. That is useful non-obvious context. However it doesn't cover key behavioral questions: what 'get' returns, what 'forget' removes and whether it's reversible, what happens when a note conflicts with an existing mapping, or any rate limits. For a mutation tool with no annotations, this is incomplete.

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 sentences, front-loaded with the resource location and its contents, followed by the actionable trigger. No filler words and the example is concrete. It could be slightly tighter but everything present 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?

The tool has a nested 'forget' object with five fields, a required action discriminator, no annotations, and no output schema. Despite this complexity, the description only covers the 'note' action meaningfully. An agent would not know how to read memory ('get' return shape), how to selectively forget, or how the actions interact. Too little for the schema's 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 description coverage is only 33%. The 'note' parameter has a schema description ('the user's correction or preference, in their words') and the description echoes the note concept, so that one is covered. But the 'forget' object and its five sub-fields (all, font, note, selector, component) have no descriptions in the schema and no explanation in the prose. The description says nothing about how to target a specific memory for removal, which is the tool's most semantically complex operation. It fails to compensate for the coverage gap.

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 explains what the memory store contains (font substitutions, component mappings, user notes, recurring problems) and gives a concrete example. However, it frames the tool as a store of knowledge rather than naming its operations. The action enum (get/note/forget) is the real purpose, and the description gives 'Save a note' as an example but never covers retrieval or forgetting. An agent can infer persistence but not the full action set from the description alone.

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?

It gives one clear actionable trigger: 'Save a note whenever the user corrects you.' That covers the 'note' action well. But there is no guidance on when to use 'get' (e.g., at session start / before making substitutions) or when to use 'forget' (e.g., user retracts a preference or a mapping is wrong). Those are exactly the decisions an agent needs to make for the other two enum values, and they are left to inference.

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