AvianSuite

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

Annotations only declare it is a non-read-only, non-destructive write. The description adds substantial context beyond that: the old fact is retained and marked superseded, the correction is itself reversible, and the receipt link should be surfaced to a human so they can check and undo. That is exactly the kind of undo/audit behavior annotations cannot convey.

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?

Four sentences, each carrying distinct load: trigger, inputs, the record_fact alternative, and the history/receipt behavior. The usage trigger is front-loaded and nothing is redundant.

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?

Despite 9 parameters, a nested evidence object, and no output schema, the description covers the operation's lifecycle (supersede, undo, receipt link) and its relationship to the sibling write tools. An agent has everything needed to invoke it correctly.

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 each of the 9 parameters is already documented. The description restates two of them (hash to replace, reason) and adds the intent behind the reason field, but adds no syntax, format, or default detail beyond the schema. 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?

States a specific verb (correct) and resource (a recorded fact), and immediately scopes it as fixing a fact that was wrong at recording time (typo, wrong customer). It explicitly contrasts with the sibling record_fact, so an agent can distinguish the two without opening schemas.

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 ('was wrong when it was recorded, and you know the right value') and an explicit when-not with the named alternative ('If the old value was right then and has since changed, use record_fact instead'). It also states the inputs to supply (hash and reason).

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 declare idempotentHint and destructiveHint=false, but the description adds context annotations cannot express: records and history persist in the store, enable_app restores state exactly, re-disabling an already-off app is safe, and a reader connection is not permitted to perform this write.

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?

Four short sentences, front-loaded with the use case, and every sentence carries a distinct fact (effect, reversibility, idempotency, authorization). No filler or restatement of the title.

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?

No output schema exists, but none is needed: the description covers the effect, the safety and reversibility profile, the idempotency case, and the auth prerequisite. An agent has everything required to invoke this correctly.

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 app enum and workspace parameter are already fully documented in the schema. The description repeats the two app names but adds no format, default, or resolution detail beyond what the schema states; 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?

States a specific verb and resource ('turn off a built-in app') and enumerates the exact targets (magpie, martin), which matches the enum in the schema. It is clearly separable from its sibling enable_app.

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 the condition for use ('workspace no longer needs' the app, tools stop being listed), names the inverse alternative (enable_app) and its effect, and states an exclusion ('a reader connection cannot disable an app'). When, when-not, and the alternative are all explicit.

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?

Goes well beyond the annotations by disclosing side effects: it initializes the app in the workspace store and registers tools (magpie_/martin_ prefixed) for every agent on the workspace, plus a client-reconnect caveat. Annotations only cover idempotency/safety, so this added context is genuinely valuable.

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?

Front-loads the action and its targets, then adds behavior and the routing hint in tight sentences. Every sentence carries distinct, non-redundant 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 3-param mutation tool with no output schema, the description covers persistence, scope (all agents on the workspace), idempotency, client caveat, and the inverse operation. Nothing an agent needs to invoke it correctly is missing.

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 schema already documents app, currency, and workspace. The description adds only the magpie/martin tool-prefix convention, which is mildly useful but does not enrich parameter meaning beyond the enum and field descriptions.

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 (turn on) plus the resource (built-in app in this workspace) and enumerates the concrete values (magpie, martin). It clearly contrasts with the sibling disable_app, so an agent can distinguish them without opening either schema.

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?

Explicitly names the alternative and the condition that selects it ('To turn the app off again, call disable_app'), and notes that re-enabling an already-on app is safe. Both the when and the when-not are stated.

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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral value by disclosing what the read spans — every fact, correction and retraction, with actor and timestamp — which tells the agent to expect an event history, not just a current snapshot.

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 sentence, front-loaded with the usage trigger and then the scope of the read. There is no filler and no repetition of the title.

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 read-only tool with no output schema, the description conveys enough about the returned content (facts, corrections, retractions, actor, time) for an agent to interpret results. It omits pagination/volume expectations and any explicit relationship to siblings, keeping it just short of complete.

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 all three parameters are already documented in the schema, including include_history's default. The phrases 'currently true' and 'how it got that way' loosely map to current-vs-historical facts, but add no format or syntax detail beyond the schema; 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?

The description gives a specific verb ('read') and a specific resource scope ('one entity'), and clarifies that the read covers facts, corrections, and retractions rather than a raw record. It implicitly separates this from the mutation siblings (record_fact, correct_fact, retract_fact), though it never names an alternative, 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?

It opens with an explicit trigger phrase ('Use to read what is currently true about one entity'), which is clear usage context. It does not state when NOT to use it or point to a sibling like list_changes for cross-entity queries, so no exclusion guidance is present.

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 declare readOnly, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely new context by disclosing what the result contains (app identity, enabled status, contributed tools) — valuable given there is no output schema — though it says nothing about ordering, pagination, or how many apps may appear.

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?

One sentence, front-loaded with the use signal, with every clause carrying information (app identity, enabled state, contributed tools). No filler or redundancy.

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 zero-required-parameter read-only listing with no output schema, the description covers what is returned well enough to call the tool correctly. It stops short of mentioning ordering or result size, which is a minor gap.

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% and the single optional workspace parameter is fully documented in the schema. The description only echoes workspace scoping via 'on this workspace' and adds no format or defaulting detail beyond the schema, so the 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?

States a specific verb and resource (list the apps built into AvianSuite) and enumerates exactly what the answer contains: built-in apps like Magpie bookkeeping and Martin CRM, their enabled state on the workspace, and the tools each contributes. This clearly separates it from enable_app/disable_app siblings.

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 opening 'Use to see...' implies the discovery use case, but it never states when not to use it or names enable_app/disable_app as the mutating alternatives. Usage is inferable rather than explicit.

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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only a little beyond that: it implies the results carry actor names and a window, which helps the caller use the output before undo_changes. No return format, pagination, or ordering detail is offered (schema covers limit/order).

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, no filler, and the primary action ('see what changed in a time window') is front-loaded before the filtering options and the undo_changes pointer.

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 6-parameter, read-only listing tool with full schema coverage and no output schema, the description covers purpose, usage context, and the downstream workflow with undo_changes. It could say a bit more about what a change record contains or how paging behaves, but nothing essential to a correct call is missing.

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 all six parameters (since, until, actor, entity_id, limit, workspace) are documented in the schema itself with formats such as RFC 3339 and duration shorthand. The description only restates the actor/entity filtering at a high level and adds no syntax or format meaning beyond the schema.

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 and resource ('see what changed') plus the scope ('in a time window') and the two optional narrowings (one agent, one entity). It also names the related sibling undo_changes, so an agent can place it without opening other schemas.

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?

Explicitly says when to reach for it: 'review an agent's work' and 'before undo_changes to find the actor name and window.' That is concrete context and links it to a workflow. It stops short of stating when not to use it or naming alternatives for pure entity inspection (e.g. get_entity).

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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value the annotations cannot: it discloses what the response contains (plan, usage, monthly cost) and that results are scoped to "this connection". It does not mention ordering, pagination or failure modes, but for a zero-argument read that is acceptable.

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, no filler. The primary purpose leads, and the follow-on sentence about reusing the workspace name is actionable rather than decorative.

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 output schema and zero parameters, the description is the only source of return-value information, and it names the key fields. It stops short of noting whether the list can be large or ordered, which would matter for an agent consuming it programmatically.

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 tool takes no parameters, so the baseline is 4. The description goes slightly further by explaining the meaning of the "workspace" argument as it is used in other tools, clarifying the identifier vocabulary an agent will need downstream.

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 (see/list) and resource (AvianSuite workspaces this connection can use) and even names the payload fields returned (plan, usage, monthly cost). No sibling tool lists workspaces, so it is trivially distinguishable from the rest of the set.

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 second sentence gives concrete workflow guidance: take a workspace name from here and pass it as the "workspace" argument of any other tool. That implies when to call it (before acting on a workspace) but states no exclusions or alternatives, which is a minor gap given no sibling overlaps.

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 (readOnlyHint=false, destructiveHint=false) establish that this writes but doesn't destroy; the description adds real substance beyond them: a new value supersedes the old while history is retained, the fact is attributed to the caller and carries evidence, and it can be corrected or undone later. It could go further on permissions or failure/duplicate behavior, but the semantics of the write are well disclosed and consistent with the non-destructive hint.

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?

Front-loaded with the triggering situation and the key alternative, and every sentence carries information. It is somewhat long at six sentences with a few overlapping ideas (history retention, correctability, receipt link), so it is efficient but not maximally tight.

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 mutation with no output schema, the description covers the important agent-facing behavior: supersession semantics, evidence retention, attribution, and what to do with the returned receipt link. It stops short of describing error/retry handling beyond what the operation_id schema entry explains.

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 every one of the 8 parameters is already documented (including operation_id idempotency and entity_id format). The description adds framing — evidence is kept so a person can check it — but no new syntax or format detail warrants going above the 3 baseline.

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 states a specific verb+resource ('record a fact' about 'a customer, ticket, order or other business record') and explicitly contrasts with the sibling correct_fact for the case where a value was never right. An agent can distinguish this from retract_fact/correct_fact without opening a schema.

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 ('when you learn something ... and want it kept, including when a value has changed in the real world') plus a named alternative and the condition that selects it ('If the recorded value was never right, use correct_fact instead'). It also gives post-call guidance about sharing the receipt link.

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 only say readOnlyHint=false and destructiveHint=false; the description supplies the crucial missing context that the fact 'stays in history, marked as retracted' and that retracting a retraction restores it, confirming the non-destructive, reversible nature. It also introduces the receipt link for undoability. It does not explain auth/permission needs, which is a minor gap.

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?

Four short sentences, front-loaded with the usage condition, then mechanics, then reversibility, then the receipt-link instruction. Each sentence carries distinct value with no filler, though the receipt-link sentence is the most tangential.

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-param mutation with no output schema, the description covers the when, the mechanics, reversibility, and even what to do with the returned receipt link. Given annotations plus a fully documented schema, this is essentially complete.

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 hash, reason, entity_id, operation_id, and workspace are already well documented. The description's 'Give its hash and a reason' merely restates two of them, adding no syntax or format detail beyond the schema. 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?

States a specific verb+resource (retract a fact) and immediately scopes it with the deciding condition: 'when a recorded fact should no longer count and there is no replacement value.' This implicitly distinguishes it from correct_fact, which handles the replacement case, so an agent can route between 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 clear when-to-use context ('should no longer count', 'no replacement value') and notes the reversal path ('retracting a retraction restores the original fact'). It never names correct_fact explicitly as the alternative, but the 'no replacement value' qualifier makes the boundary inferable.

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 flag destructiveHint=true; the description earns credit by explaining why and what is actually affected: saving an existing name 'moves it to the current state' (i.e. the prior checkpoint is overwritten), while facts remain untouched. It does not cover permissions, workspace scoping rules, or side effects on change history, so it is strong but not exhaustive.

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?

Four short sentences, front-loaded with the usage trigger and no wasted preamble. The final sentence about facts is slightly redundant given the earlier overwrite statement, but it preempts a misreading of destructiveHint.

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 two-parameter tool with no output schema, the description covers when to call, what it does to existing state, and how to restore from it. It omits any note on what is returned (e.g. the saved checkpoint name) or on how checkpoints interact with workspace scoping.

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 adds value by demonstrating the name convention ('before-import') and by linking the name to the later 'checkpoint' argument of undo_changes, which the schema alone does not convey. The optional workspace parameter is left entirely to the schema.

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+resource ('name the current state'), gives a concrete example ('before-import'), and explicitly contrasts its non-effect with fact mutation ('never changes any facts'). An agent can distinguish it from record_fact/correct_fact/retract_fact purely from the text.

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 ('before a risky job, such as an import') and names the exact follow-up path ('call undo_changes with checkpoint set to this name'), so restore flow is unambiguous. This is explicit when-to-use plus the alternative tool, not implied guidance.

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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail the annotations do not carry: that it reveals the actor name writes are attributed to and the current root, which matters for later write calls.

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, no filler, with the invocation trigger front-loaded and the secondary return content ('Also returns the current root') placed last. Every clause carries 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 read-only, zero-required-parameter tool with full schema coverage, the description enumerates the four things the caller learns (health, facts presence, actor, root), which is the right substitute for a missing output schema. It stops short of describing return format or any error/offline signaling, which would complete 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?

One optional parameter with 100% schema description coverage, which already explains workspace semantics and the default behavior. The description adds no workspace-format or resolution detail beyond that, so the schema does the heavy lifting and 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?

Concrete verb (check) plus exactly what is checked: store reachability/health, whether any facts exist, the actor name attributed to writes, and the current root. No sibling tool (list_apps, get_entity, record_fact, etc.) overlaps with this diagnostic view, so the agent can separate it immediately.

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?

Opens with an explicit trigger phrase ('Use to check that the store is reachable and healthy...'), giving clear context for invocation. It does not state when not to use it or name an alternative, but there is no competing status/diagnostic sibling to route away from.

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 declare readOnlyHint=false and destructiveHint=false; the description explains why the operation is non-destructive ('each reversal is a new retraction, so an undo can itself be undone') and adds behavior annotations do not carry: dry-run by default, drift protection via plan_id, and that non-fact events are listed as skipped rather than reversed.

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?

Front-loaded with the trigger scenarios, then the two modes, then the dry-run/confirm contract. Every sentence carries a distinct rule (mode selection, confirmation, idempotency of the undo itself, skipped events) with no filler.

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 9-parameter, zero-required, no-output-schema tool with a two-phase write protocol, the description covers everything an agent needs: how to pick parameters, what the dry run returns, how to confirm, and what happens to non-fact events. Nothing material is left to inference.

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, but the description adds real cross-parameter semantics the schema does not: since and checkpoint are alternatives, actor is optional specifically when checkpoint is used, until must be the absolute value the dry run returned, and confirm+plan_id together guard against stale windows.

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+resource (reverse changes) and immediately scopes it to two concrete scenarios (a bad import or runaway loop, and restoring to a checkpoint from save_checkpoint). This cleanly distinguishes it from siblings like retract_fact, correct_fact and save_checkpoint, which an agent could otherwise confuse with it.

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 explicit when-to-use conditions, names the two mutually exclusive entry points (since for a window, checkpoint to restore), and spells out the required follow-up workflow (dry run first, then re-call with the returned until/since, plan_id and confirm: true). It also states a hard exclusion: a confirmed call refuses a relative since.

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