graymatter

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

The description says 'restore,' which implies a state-changing operation, yet annotations declare readOnlyHint=true and destructiveHint=false. This is an annotation contradiction: nothing reconciles the side effects of restoring a checkpoint with the claim that the tool is read-only.

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 a single front-loaded sentence with no filler. It states the operation clearly and compactly.

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 tool with a complete schema, the minimum callable information is present. However, the definition omits usage guidance and leaves the read-only/restore contradiction unresolved, so an agent cannot fully judge the tool's effect or when to invoke it.

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 schema already documents agent_id fully. The description's 'for an agent' adds no new meaning beyond the schema, so the baseline of 3 applies.

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 names a specific action ('restore'), a precise object ('the latest checkpoint'), and the target ('for an agent'), making it immediately distinguishable from sibling checkpoint_save and the memory_* tools. No ambiguity about what the tool does.

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 no guidance on when to choose this tool over checkpoint_save or the memory tools, and it does not state prerequisites or exclusions. The intended context is only implicit in the verb 'restore'.

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

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

Annotations already indicate this is not read-only and not idempotent, and the description adds that it persists agent state. However, it does not explain overwrite behavior, whether checkpoints accumulate, or what happens to existing checkpoints. No contradiction with annotations.

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 with no filler words. Every word contributes to the meaning.

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 and parameters are fully documented in the schema, but the description lacks lifecycle context such as whether saving overwrites a previous checkpoint, how it relates to checkpoint_resume, or what the return value is. It is minimally viable but not rich enough to be fully self-sufficient.

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 adds no extra meaning about the agent_id or state parameters beyond what the schema already provides.

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 'Save' and a specific resource 'checkpoint of current agent state'. The name and description clearly distinguish it from sibling tools like checkpoint_resume and the memory_* tools.

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?

No guidance is given about when to use checkpoint_save versus checkpoint_resume or the memory tools. There are no conditions, exclusions, or alternative routing cues.

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

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

The annotations are all false and provide no meaningful safety or behavior hints. The description merely restates the tool's purpose ('store') without adding operational context such as whether it appends without overwriting, any persistence guarantees, or what happens to existing memories. No contradiction exists, but no behavioral detail is disclosed beyond the annotations.

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 a single, front-loaded sentence with no filler. Every word contributes to conveying the core action, and it is appropriately sized for a simple two-parameter write operation.

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?

This is a simple tool with two required parameters and no output schema, so the description is adequate at a basic level. However, it omits guidance on when to choose this tool over siblings and does not explain what the agent should expect as a result (e.g., confirmation, returned memory ID), leaving a moderate gap for autonomous decision-making.

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 schema documents both parameters (text and agent_id) thoroughly. The description adds no extra parameter-level meaning: it mentions 'new fact' which mirrors the schema's 'observation or fact', and doesn't clarify formats, constraints, or relationships beyond what the schema already provides. Baseline 3 applies.

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?

Description is clear: 'Store a new fact in GrayMatter memory' has a specific verb and resource, and the action of adding a memory is distinct from the sibling tools (search, reflect, checkpoint). However, it does not explicitly differentiate itself from these siblings or mention their existence, so it stops short of 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 no guidance on when to use this tool versus alternatives like memory_search or memory_reflect. The intended use case (adding a new fact) is only implied by the verb 'store' and the tool name; no explicit context, conditions, or exclusions are provided.

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

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

The description explicitly includes 'forget' as a core action, which is a destructive memory operation, yet the annotations declare destructiveHint: false. This is a direct contradiction between the described behavior and the structured metadata. Beyond that, the description adds little behavioral context that the annotations do not already cover or contradict.

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 a single dense sentence that front-loads the action list and then supplies the usage triggers. It contains no filler, no repetition of schema content, and every clause contributes useful selection information.

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 tool with four parameters and six distinct actions, the description plus full schema coverage is mostly sufficient. It explains when to use the tool and what actions are available. The main gap is not explaining the semantics of 'link' or 'pin' beyond their names, but the schema descriptions fill in the parameter mechanics.

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 itself does not add parameter-level detail, but the schema already explains text, target, agent, and action sufficiently. No additional semantic explanation is required.

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 opens with a concrete list of actions and the resource they act on: 'Add, update (supersede), forget, link, or pin your memories.' This immediately identifies the tool's scope and distinguishes it from sibling tools like memory_add, which only handles adding.

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 triggering conditions: 'Use when you notice a contradiction, finish a task, learn a durable preference that should persist, or the user declares something permanent.' This is clear context for when to invoke the tool, though it does not explicitly mention when not to use it or name alternatives.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive, so the bar is lower. The description adds meaningful behavioral context by revealing the two-call pattern and the existence of a shared memory namespace, which the agent would not know from annotations alone.

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 deliver the core purpose and the critical usage pattern with no filler. The primary verb and resource are front-loaded, and every clause contributes useful information.

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 simple, read-only search tool, the description combined with the well-documented schema and safety annotations covers everything an agent needs to call it correctly. The only notable behavior — the two-call pattern — is explicitly included.

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 the baseline is 3. The description goes beyond the schema by specifying the exact agent_id values to use ('your agent_id' and '__shared__') and clarifying that queries are natural-language matches for stored facts, adding real semantic value.

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 names a specific verb ('Search') and resource ('GrayMatter memory') with a clear scope ('relevant facts'). It is readily distinguishable from sibling memory tools like memory_add and memory_reflect.

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, actionable usage instructions: call once for the current agent_id, then again with agent_id '__shared__' for user-level preferences. This tells the agent exactly how to invoke the tool effectively.

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