Engram

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safety profile is supplied structurally. The description usefully adds validation behavior and failure semantics (which steps are gated, and that the result explains what is missing), but it never explains why the tool is flagged destructive or what state the 'activated' milestone irreversibly commits.

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 tight sentences with the purpose front-loaded, followed by the acceptance precondition. The parenthetical glosses each earn their place and nothing is padded.

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-parameter tool with no output schema, the description covers purpose and step preconditions, which is most of what an agent needs. It stops short on sibling differentiation (activation_stage / activation_status) and on the implications of the destructive flag, leaving meaningful gaps for a mutation tool.

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 goes beyond the schema's bare enum list by glossing the milestone meanings (brain_init = build started, activated = live) and describing the gating condition per step. It adds genuine semantic value over the enum values themselves.

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 ('Records the brain's build milestone') and enumerates the accepted steps with brief glosses (brain_init = build started, activated = live). It does not distinguish itself from the closely-named siblings activation_stage and activation_status, so an agent cannot tell from the description alone which of these three to pick.

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 a real precondition: 'scheduled' and 'activated' are accepted only once the brain is built, otherwise the result explains what is missing. That is useful when-to-use context, but there is no explicit guidance on when to call this versus activation_stage, activation_status, or schedule_set.

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=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds the useful context that the value surfaces on the Engram console during the build, but it never explains the destructive/idempotent consequence — i.e. that recording a stage overwrites the previously recorded status and counts for that stage.

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 compact sentences with the action and scope front-loaded and no filler. The parenthetical enumerations of stage and status values slightly duplicate the schema enums, which is the only 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 five-parameter write tool with full schema coverage and annotations carrying the safety profile, the description covers what the tool records and where it is displayed. The only real gap is the overwrite semantics implied by destructiveHint=true and the role of the brain parameter, both of which are left to structured fields.

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 parameter including brain, done and total is already documented in the schema. The description restates the stage and status enumerations and mentions the optional done/total counts, adding no format or default semantics beyond what the schema provides, which matches the baseline 3.

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 (Records) and resource (progress on one stage of the build) and enumerates the allowed stage and status values, so the agent knows exactly what it writes. It never distinguishes itself from near-name siblings such as activation_report, activation_status, stage_commit or stage_propose, so an agent cannot route between them 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?

"Shown on the Engram console while the brain is being built" implies the usage context (during an active build) but gives no explicit when-to-use/when-not guidance. With activation_report, activation_status, stage_commit and stage_propose in the sibling set, the absence of any routing rule leaves the choice to inference.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by disclosing what the payload contains (phase, step checklist with the tool that records each step, readiness to go live, and settings requiring user confirmation), which is beyond what the annotations provide.

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 leads with the core action and then lists the returned fields efficiently, with no filler. The inline enumeration is dense but each item earns its place by describing a distinct piece of state.

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, the description carries the burden of describing return values and does so thoroughly (phase, checklist, readiness, depth, pending settings). Safety is covered by annotations, and the only missing element is routing against sibling activation tools.

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?

Only one parameter exists and its schema description coverage is 100% ('Brain id or name. Defaults to the active brain.'). The description adds no parameter-level information and does not mention the active-brain default, so the schema does the work 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?

The description states a specific verb and resource ('Returns the state of building a brain from the user's sources') and enumerates the returned content (phase, checklist, readiness, depth, settings). It is clear in isolation, but it never differentiates itself from the closely related siblings activation_report and activation_stage, so an agent cannot easily tell which status tool to pick.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as activation_report or activation_stage despite their near-identical naming. The usage is only inferable from the returned content, leaving the agent to guess which activation tool to call.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the useful scoping detail that only *open* items are returned, but nothing about volume, pagination, or ordering.

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 naming the resource and scope, with no wasted words or 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 simple, read-only, zero-required-parameter list tool with full schema coverage and annotations carrying the safety profile, the description is adequate. Minor gaps (ordering/volume) are unsurprising given no output schema.

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 'brain' parameter is fully documented (id or name, defaults to active brain) in the schema itself. The description adds nothing beyond that, so 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 (Lists) and resource (a brain's open attention items), so the operation is clear. It does not, however, explicitly differentiate itself from the sibling attention_set, leaving the read/write split to be inferred.

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 says what it returns but never states when to use this versus alternatives such as attention_set, nor any prerequisites (e.g. needing an active brain). The 'Today screen' reference is context, not usage 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the write-and-overwrite profile is covered structurally. The description usefully reinforces the replacement semantics ('Replaces a brain's list'), meaning omitted items are dropped, but it omits return behavior and contains an internal inconsistency (it says up to 10 items while the schema allows maxItems 30), leaving the agent unsure of the real cap.

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 tight sentences: the operation and its visible effect are front-loaded, followed by the taxonomy. Nothing is padding, though the 'up to 10' claim conflicts with the schema's maxItems of 30 and would have been better left out or aligned.

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?

There is no output schema, so the description needn't explain returns, and annotations carry the safety profile. For a destructive, brain-scoped overwrite tool, however, it should say what happens to items that are not re-supplied and confirm the effective item cap, which it leaves ambiguous.

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%, which sets a baseline of 3, but the description goes beyond the schema by enumerating the valid kind values (fact_check, commitment_due, decision_overdue, owner_check, tidy_up, reminder) even though the schema declares 'kind' as an unconstrained string with no enum. That is genuinely additive. It does not explain rank, refs, or label semantics.

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 ('Replaces'), a specific resource ('a brain's list of open attention items'), and a concrete scope ('shown on the Engram console's Today screen'), which is far more than a restatement of the name. It implicitly distinguishes itself from attention_list via 'Replaces', but never names that sibling, so an agent must infer the contrast.

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 explains what the list is for (the Today screen) but never states when to call this tool versus the obvious sibling attention_list, nor any precondition such as needing the brain selected first. Usage must be inferred entirely from the name and the word 'Replaces'.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds only the shape of the content returned (topic tree plus memory counts); it says nothing about depth, ordering, or whether counts are recursive, so it does not go far 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?

One sentence, front-loaded with the verb and resource, and it packs the two useful facts (concept/sub-concept tree, memory counts) 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?

With no output schema, the description has to carry the return-value burden; it names the returned content but omits structural details such as tree depth, ordering, and whether the counts aggregate sub-concepts. For a single optional parameter and no output schema this is adequate but leaves real gaps.

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% and the single optional parameter ('brain' – id or name, defaults to the active brain) is fully documented in the schema. The description's phrase 'a brain's' implicitly references that parameter but adds no format, default, or resolution detail beyond it, 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 (returns) and resource (a brain's topic tree, concepts and sub-concepts) plus what is attached to each node (memory counts). It is clear what the tool produces, but it never distinguishes itself from the closely named sibling topic_summary_get, which an agent could easily confuse it with.

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?

There is no guidance on when to use this versus topic_summary_get, memory_list, or brain_list, and no statement of prerequisites or context. The agent must infer usage entirely from the name and the one-line description.

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 it is a non-readonly, non-idempotent, non-destructive write. The description adds a genuinely non-obvious behavioral fact beyond those hints: creating a brain also makes it active, mutating global state. It does not say what happens to the previously active brain or whether creation is reversible, so it stops short of full disclosure.

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 that front-loads the action and its side effect, with no filler. It is arguably under-specified rather than bloated, but as written every clause 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?

There is no output schema, so nothing is owed on return values, and annotations cover the safety profile. However, for a state-mutating create with two undocumented enum parameters, the description leaves the storage-mode choice and the effect on the previously active brain unexplained.

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% — only 'name' is documented, while 'kind' and 'storageMode' are bare enums. The description's examples ('different job or a personal context') loosely gesture at the 'kind' values, but it says nothing about 'storageMode' (local vs cloud) or the tradeoffs between them, so 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?

States a specific verb and resource (creates a new brain) and adds the key consequence that the new brain becomes active. It implicitly distinguishes itself from siblings like brain_list, brain_select, and brain_current by being the creation operation, though it does not name those alternatives explicitly.

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 parenthetical 'for example for a different job or a personal context' sketches when a new brain is warranted, which is implied usage guidance. It never states when to prefer brain_select (switch existing) over brain_create, nor any prerequisites or exclusions, leaving the agent to infer the boundary.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the gloss that 'current' means the active brain; it says nothing about permissions, failure modes, or what happens when no brain is active.

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 seven-word sentence with zero filler, and the essential qualifier ('currently active') is front-loaded. Nothing in it 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?

For a trivial zero-parameter getter with no output schema, the definition is minimally viable: it tells the agent what is fetched but not what the returned brain object looks like (identifier, name, fields) or what is returned when no brain is active. Slightly more return-value context would have made it 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?

The tool takes zero parameters, which sets the baseline at 4 per the rubric. There is no parameter syntax or semantics for the description to compensate for.

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 ('Returns') and resource ('the brain that is currently active'), clarifying that 'current' means the active/selected brain rather than any brain. It is clear in isolation but never differentiates itself from siblings like brain_list or brain_select, so an agent must infer the distinction from names 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?

The description offers no when-to-use guidance, no prerequisites, and no mention of alternatives such as brain_list (enumerate brains) or brain_select (change the active brain). Usage has to be inferred entirely from the tool name.

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, idempotent, non-destructive, closed-world. The description adds useful content beyond that: it discloses scope (includes team-shared brains) and that it marks the active one. It doesn't describe return structure, but readOnly annotations reduce the burden.

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?

Single well-formed sentence, front-loaded with verb and resource, adding two meaningful qualifiers without waste.

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-param read-only list tool whose safety profile is covered by annotations, this is nearly complete. Missing only an explicit relationship to siblings like brain_current/brain_select, which would aid routing.

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?

Zero parameters, so baseline 4. Description correctly conveys there's nothing to configure and focuses on output semantics instead.

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 (List) and resource (brains), and clarifies scope: user's own plus team brains shared with them, and flags the active one. Distinguishable from siblings like brain_current (single active brain) and team_list.

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?

Implies usage (enumerate brains) but does not explicitly say when to use this vs brain_current, brain_select, or team_list. The agent must infer that this is the enumerator versus the single-active-brain accessor.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds no behavioral context of its own: nothing about whether the switch persists across sessions, affects other concurrent work, or what happens when an unknown id/name is supplied.

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 short sentences with no filler, and the core action is front-loaded before the usage hint. Nothing can be trimmed without losing 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 two-parameter toggle with no output schema and annotations covering safety, the description is adequate. The notable omission is parameter interaction semantics (id vs name precedence/mutual exclusivity) and any note on the effect or failure mode of the switch.

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 both parameters are already documented, giving a baseline of 3. The description's 'by id or name' adds slight clarification of intent, but with zero required parameters and two optional ones it never resolves the ambiguity of what happens if both are supplied or whether they are mutually exclusive.

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 action ('Makes another brain the active one') and the two lookup keys ('by id or name'), which is enough to distinguish it from brain_list, brain_current, and brain_create. It is close to the title 'Switch active brain', but the added 'another brain' and lookup-key detail lift it above pure restatement.

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?

'Use when the user wants to work in a different brain' gives a clear triggering condition. It stops short of naming alternatives (brain_current, brain_list) or stating when not to use it, so it is clear context without exclusions.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: upsert semantics, the duplicate-detection side effect on create, and the accepted status vocabulary, which is genuinely useful for anticipating outcomes.

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?

Three tight sentences, no filler, with the primary create/update behavior front-loaded before the parameter hint and the duplicate caveat. Every sentence 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?

For a 13-parameter mutation tool with no output schema and low schema coverage, the description covers the core lifecycle but omits the meaning of several parameters and any return/conflict semantics beyond duplicates. Adequate but with visible gaps.

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 38% across 13 parameters, so the description must compensate but only partially does. It clarifies `id`, `text`, `status`, and implies owner/counterparty/due, but leaves `entityId`, `source`, `stateNote`, `updatedBy`, `observedAt`, `brain`, and especially `ifUnmodifiedSince` (optimistic concurrency) unexplained.

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 ('creates or updates a tracked commitment') and crisply defines the domain object as what is owed, by whom, to whom, and by when. The create-vs-update distinction via `id` is explicit, so an agent can tell this apart from read-only siblings like open_commitments without opening the 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 clear operational context: pass `id` to update, omit it to create, and expect duplicate suggestions on create. It does not name alternative tools (e.g., open_commitments for reading existing commitments), so exclusions are left implicit.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by documenting the returned payload sections, which substitutes for the missing output schema. It stops short of describing ordering, counts, or behavior when a section is empty.

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 the verb and resource first, followed by a scannable list of return sections. Every clause maps to a distinct piece of returned data, so nothing is waste.

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, the description usefully enumerates what comes back, which is the key missing structured information. It omits minor but real details: item ordering, limits, and behavior when the brain has no commitments or questions, so it is strong but not exhaustive.

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?

There is only one parameter and schema description coverage is 100%, including the default-to-active-brain behavior, so the schema carries the semantics. The description adds nothing about the brain argument. 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 (Returns) plus the resource (a brain's review data for today) and then enumerates the exact sections: open commitments, thin memories, sources with last-read dates, unanswered questions, stale topic summaries. This lets an agent distinguish it from narrower siblings like open_commitments, attention_list, and topic_summary_get, since this is clearly an aggregated daily dashboard.

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 name and content imply a start-of-session orientation call, so the when-to-use is inferable, but there is no explicit guidance such as 'use this for a daily overview instead of calling open_commitments and topic_summary_get separately'. No exclusions or alternatives are named.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds real value: the note is deliberately content-free, it is routed to the Engram team, and sensitive payloads must be excluded. It stops short of describing the write's result or any rate/duplication behavior.

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, zero filler, with the core action and scope front-loaded and the privacy constraint placed as the closing guardrail. Every clause 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?

There is no output schema, but the tool is a simple append-style log, and the description covers purpose, triggers, and the sensitive-data constraint. Minor gaps remain on whether the call returns an id or dedupes repeats, which an agent could want in order to verify the log landed.

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% with enums spelled out for kind and severity, so the schema already carries parameter meaning. The description only reinforces the 'content-free' rule for detail, adding no format, default, or unit information 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 (records) and resource (a short, content-free note) plus the triggering situations (build, daily update, session). An agent can distinguish this diagnostic-logging tool from memory/session siblings like memory_append or run_checkpoint without opening the 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?

Enumerates concrete when-to-use triggers (refusal, retry, stall, tool or environment error) and gives a clear when-not constraint ('Never include message bodies, names or query text'). It does not name a competing sibling to route against, which keeps it from a 5.

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 this is a non-destructive, non-idempotent write (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely useful behavior beyond that: earlier content and history are preserved, and an update identical to the latest is skipped. It stops short of covering permissions or what happens on conflicts.

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?

Three short sentences, front-loaded with the core action and preservation behavior, then the dedup rule, then the usage cue. No filler and 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 14-parameter tool with nested objects, 29% schema coverage, and no output schema, this description is far too thin. It omits any explanation of the many advanced parameters (force, trust, supersedes*, contradictionAck) that an agent would need to call the tool beyond its minimal two required fields.

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 29% across 14 parameters, so the description is expected to compensate but does not. Undocumented fields such as force, trust, supersedesBody, supersedesLayer, contradictionAck, and section are left entirely unexplained, and only 'dated' loosely gestures at observedAt.

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 ('adds a dated update layer to an existing memory') and its non-destructive nature ('keeping its earlier content and history'), which implicitly separates it from the replace-style memory_upsert. It does not name a sibling explicitly, but the append-layer framing is distinct enough for an agent to choose correctly.

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?

'Use for new developments on something already saved' gives implied when-to-use context. However, it never names the closest alternative (memory_upsert) or states any when-not condition, so the agent must infer the append-vs-upsert boundary from semantics alone.

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 and idempotentHint=true, so the bar is lower, yet the description adds the key mechanic the annotations cannot convey: the effect is immediate on visibility and becomes permanent erasure after 7 days. That explains why a destructive hint applies to what sounds like a hide. It does not say whether the archive can be reversed within that window or what the call returns, leaving a small 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?

Two short sentences, each carrying distinct information: the effect on retrieval, and the two-stage timing. The non-destructive framing is front-loaded exactly where an agent deciding between archive and delete would look.

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 mutation with no output schema and annotations covering safety, the description supplies the essential behavior — immediate hiding plus deferred permanent erasure. Only reversibility and confirmation behavior are unaddressed, which is minor.

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 both parameters (id, brain) are already documented in the schema, and the description adds nothing about id format or brain scoping. Baseline 3 applies when the schema carries the semantics.

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 precise verb (hides) and resource (a memory) plus the immediate effect on search and recall, and contrasts with deletion in the same sentence. It stops short of naming memory_delete explicitly, so the routing signal is implicit rather than explicit.

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?

"Without deleting it" implies this is the soft-removal path versus memory_delete, and the 7-day window implies urgency semantics, but neither the alternative nor a when-to-use condition is stated outright. An agent must infer the choice between archive and delete.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still adds real context: the cascading scope (update layers and links are destroyed), irreversibility ("Cannot be undone"), and the confirm guard, which the annotations do not express.

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?

Three tight sentences with the destructive action and cascading scope front-loaded, followed by the precondition and the reversible alternative. No sentence 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?

For a destructive delete tool with no output schema, the description covers what is deleted, the confirm requirement, irreversibility, and the safer alternative. Combined with annotations, an agent has everything needed to call it correctly and cautiously.

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 id, brain, and confirm are already documented in the schema, including that confirm is the exact title. The description only reinforces the confirm requirement rather than adding new syntax or format detail, so the baseline 3 is appropriate.

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 (deletes), resource (one memory), and unusual scope (its update layers and links), so an agent knows exactly what is removed. It is clearly distinguishable from the sibling memory_archive, which it explicitly calls out as the reversible counterpart.

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?

Names the alternative (archiving) and the condition that selects it (reversibility), and states the precondition for using this tool (confirm must equal the memory's exact title). When-to-use, when-not-to-use, and prerequisites are all 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context: retracted layers are excluded by default and only surface as an audit trail when requested, plus a note that certain flags reduce the payload.

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, zero filler, with the primary return contract front-loaded and the filtering caveat second. 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 single-item getter with no output schema, the description supplies exactly the missing piece: what the response contains. Annotations handle safety and the schema handles parameters, so nothing an agent needs is absent.

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 are already documented, including retracted's default and lastLayers' bounds. The description's synthesis that lastLayers/section/bodyOnly 'return less' adds a little framing but no syntax or semantics 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 ('Returns one memory') and enumerates the returned content (body, dated update layers, links, source references). The singular scope distinguishes it cleanly from memory_list, memory_search and recall without needing their 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?

The description implies when the optional parameters apply (retracted off by default; lastLayers/section/bodyOnly narrow output), but it never says when to choose memory_get over memory_search, recall, or memory_list. Usage is inferable rather than 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?

Adds real behavioral context beyond the annotations: matched titles update existing memories rather than creating duplicates, and the 500-item cap. Since annotations already flag destructiveHint=true and idempotentHint=false, this disclosure of the overwrite rule is the meaningful extra, though partial-failure and return behavior remain unstated.

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 clauses in a single sentence, front-loading the capacity and upsert rule before the usage cue. Nothing is wasted or repeated from the annotations.

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 destructive, non-idempotent bulk write with no output schema, the definition covers capacity, the overwrite rule, and the primary use case, while annotations supply the safety profile. The remaining gap is what happens on partial failure or validation errors within a batch.

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?

At 67% schema coverage the schema carries most parameter detail, and the description only touches 'items' via the title-matching rule. 'brain' and 'returnIds' get no added meaning, and the nested item fields are deferred entirely to the schema's reference back to memory_upsert.

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 concrete verb and resource ('saves ... memories'), plus scope ('up to 500 ... in one call') and the title-based upsert semantic. It is distinguishable from memory_upsert by the bulk framing, though it never names the sibling explicitly.

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?

'Use when the user wants to load many notes at once' gives a clear triggering condition. It stops short of an explicit when-not or routing statement (e.g. use memory_upsert for a single note), so the agent must infer the boundary itself.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the brain-scoping context but omits notable behavior such as archived memories being excluded unless includeArchived is set, plus any ordering or result-size limits.

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; the core action and its optional filters lead. It is efficient, though brevity here coincides with the missing detail noted in other dimensions.

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, the description carries the burden of explaining what a listing returns, and it does not: no ordering, no pagination, no indication whether archived items are omitted. For a four-parameter read tool in a crowded family, this is the minimum viable.

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 75%, so most parameters (type, brain, concept) are self-documenting. The description only restates 'type or concept' and never addresses includeArchived, the one parameter lacking a schema description, so it adds little 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 ('Lists') and resource ('memories') with the scoping dimension ('in a brain'). However, it does nothing to separate itself from near-siblings like memory_search, memory_get, and recall, so an agent must infer which of the listing/retrieval tools fits.

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 when-to-use or when-not-to-use guidance is given, and no alternatives are named despite memory_search and memory_get sitting in the same family. 'Optionally filtered by type or concept' implies a browsing use case but never states it or contrasts it with searching.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the ranking strategy and the returned fields (id, title, type, snippet), but says nothing about scoring behavior, empty-result handling, or cross-brain scope.

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, tightly packed sentence with no filler, and the core action and retrieval method are front-loaded before the return fields. Every clause 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?

With no output schema present, the description shoulders the return-value burden and does so adequately by naming the four returned fields. Combined with 100% schema coverage for inputs, an agent has enough to call it, though ordering and scope semantics remain implicit.

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 parameter (query, type, brain, limit) is already documented in the schema, including defaults and constraints. The description adds no syntax, format, or matching-semantics detail beyond that, 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 gives a specific verb (search) and resource (memories), plus the retrieval method (semantic + keyword) and the fields returned. It distinguishes itself from memory_list by implying ranked relevance, but it never names or contrasts against plausible siblings like memory_list or recall, so an agent must infer the boundary.

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?

Usage is only implied: 'search over memories' tells the agent this retrieves matches, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as memory_list or recall. The agent must infer selection from the name alone.

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=false and destructive=true, so the bar is lower. The description adds genuinely useful behavior beyond them: title-based dedup/merge, the requirement to set mode='replace' to overwrite an existing body by id, and the fact that replacement is destructive to the existing body.

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?

Three tight sentences with zero filler, and the core upsert/mode behavior is front-loaded. Slightly denser phrasing could have surfaced the create-vs-update distinction even faster, but it is efficient overall.

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 an 18-parameter mutation tool with no output schema and 50% param coverage, the description covers the essential upsert/replace mechanics but omits the meaning of many optional flags. An agent can call the happy path correctly, but not fully exploit the tool's capabilities from the description alone.

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 50%, so half of the 18 parameters are undocumented in both schema and description. The description clarifies the critical interplay of id, mode, and title, but leaves notable params (shallow, confirmed, userConfirmed, contradictionAck, supersedes) entirely unexplained. Baseline 3 is appropriate given it only partially compensates 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?

States a specific verb+resource ('Creates a memory for one entity... or updates the memory with the same title') and explains the upsert semantics precisely, including what identifies an existing memory (title, or id). It does not name sibling tools like memory_append or memory_archive to distinguish itself, so it falls 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?

Provides a clear usage condition ('Use when the user shares a durable fact worth keeping'), which is real guidance. However it gives no when-not, no prerequisites, and does not route the agent to alternatives such as memory_append or memory_archive when the intent differs.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that this is a filtered list (open only, own commitments by default) and mentions due dates and status. It doesn't explain things like result limits, ordering, or pagination behavior, which would improve behavioral context.

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 concise sentence that front-loads the key information: what it lists, the scope, and the returned fields. No wasted words.

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?

Given 6 parameters with low schema coverage and no output schema, the description is somewhat thin. It covers the default owner and the concept of 'open' but leaves gaps on parameters like brain, since, and includeReassigned. Adequate but not complete for a tool with this many undocumented options.

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 17%, so the description should compensate for the undocumented parameters. It only clarifies the 'owner' default ('user's own') and indirectly suggests the 'includeClosed'/'includeDone' semantics via 'not yet closed'. Parameters like 'brain', 'since', and 'includeReassigned' are not explained at all, leaving significant gaps.

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 (Lists) and resource (open commitments) with the key scope (not yet closed, defaulting to the user's own). It doesn't explicitly differentiate from commit-related siblings like commitment_set, but the 'lists' framing and open filter are clear enough to distinguish this as a read operation.

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 mentions the default behavior (user's own commitments), which gives some usage context, but doesn't say when to use this versus alternatives like commitment_set or recall. No explicit when-not-to-use 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, idempotentHint true and openWorldHint false, so safety is covered. The description adds value beyond that by describing the response shape (summary, recent updates, source links, related memories) and a retrieval mode (shared memories via `from`), which annotations don't convey. No output schema exists, so this return-shape description is doing real work; only pagination/limit behaviour is missing.

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 core action and followed by the usage scope and the alternate `from` mode. No filler, no restatement of the tool name.

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 tool with no output schema, the description covers the return payload, the natural-language query usage and the shared-memories alternative. It lacks detail on `hops`, `limit` and `detail` behaviour, but annotations carry the safety profile and the schema carries their definitions, so an agent can call 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 coverage is 83%, and the two parameters explained in prose (`from` for shared memories, plus the general retrieval scope) are already documented in the schema. `hops`, `brain`, `limit` and `detail` are not elaborated beyond their schema descriptions, so the description adds little beyond what structured data provides — baseline 3.

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 specific verb and resource — 'Answers a natural-language question from the user's brain' — and then enumerates the exact return payload: relevant memories, summary, recent updates, source links, related memories. That level of specificity distinguishes it clearly from memory_search and memory_get siblings (raw search / single fetch).

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 a concrete usage scope ('questions about the user's own people, projects, decisions and history') and explains the key alternative mode ('Optional `from` searches memories other people have shared with the user instead'). It doesn't explicitly say when NOT to use it in favour of memory_search, but the context is clear enough for an agent to pick correctly.

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 destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds genuinely behavioral context — that 'todo' terminates the run and that outcome is a binary ok/halted — but never explains why the tool is destructive (does it overwrite an earlier checkpoint?) or what a repeat call for the same step does.

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 with no padding, front-loaded with the core action and then the run-closing rule. It could be marginally tighter, but 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?

With no output schema and a nested evidence object, the description covers the write semantics but omits the return value, whether evidence/errorClass are enforced conditionally on outcome, and any notion of ordering or retry behavior for a non-idempotent, destructive call. Adequate but with clear gaps.

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 baseline is 3. The description goes further by coupling each outcome value to its payload ('ok with evidence counts, or halted with an error class'), which effectively documents the conditional pairing of evidence vs errorClass that the schema leaves unstated, since neither is marked 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?

States a specific verb and resource ('Records the outcome of one step of a daily update run') and narrows the payload to two cases: ok with evidence counts, or halted with an error class. An agent can distinguish it from run_start/run_status/run_recap, though it never names those siblings to sharpen the routing.

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?

Usage is implied rather than stated: it must be called during a run (runId 'from run_start'), and the 'todo' step closes the run, which tells the agent when the sequence ends. There is no explicit when-to-use/when-not guidance and no mention of alternatives for reading run state.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope semantics ('since a timestamp (usually the run's start)') and return content, but says nothing about pagination, ordering, or result size limits for what could be an unbounded list.

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 that states what is listed, the filter, and the returned fields without filler. It is slightly dense with three parenthetical clauses, but every clause 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?

With no output schema, the description does name the key returned fields (confidence, depth), which partially compensates. Combined with annotations covering safety and a fully documented two-parameter schema, an agent has enough to invoke it correctly; only pagination/ordering behavior 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 both parameters are already documented in the schema. The description restates the 'since' meaning ('usually the run's start') which the schema already conveys ('usually the run's startedAt'), adding no new syntax or format detail. Baseline 3 is appropriate.

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 ('Lists every memory created or updated since a timestamp') plus the returned fields (confidence and depth) and the intended review workflow. It is clear and self-contained, but it never names or contrasts itself with the obvious sibling memory_list/memory_search, so an agent must infer the distinction.

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 trailing clause 'so the user can review and correct what was written' implies the usage context (post-run review of what a run wrote), but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent is left to infer that this is the run-scoped counterpart to memory_list.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds the non-obvious 45-minute dedup window and the duplicate:true signal. That is real behavioral context beyond the structured fields, though it omits cost/duration or side effects of actually launching a run.

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 verb and outcome in the first clause, then enumerates the returned plan contents. The enumeration is dense but informative; only the long list of plan components pushes slightly past what is needed to select and call the tool.

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?

There is no output schema, so the description carries the burden of describing the return payload, and it does so thoroughly (id, start time, per-brain state, sources, memories, topics, questions, commitments, steps, plus the duplicate case). Combined with annotations covering safety, an agent has everything needed to call 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 coverage is 100% with a single well-documented boolean, so baseline is 3. The description adds value by explaining the default behavior that force overrides (the 45-minute window and the duplicate return), giving the parameter meaning in context rather than restating it.

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?

Names a specific verb and resource ('Starts a daily update run') and immediately specifies what is returned (id, start time, plan). This clearly distinguishes it from siblings like run_status, run_checkpoint and run_recap, which are about inspecting or recording an existing run.

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?

Explains the key invocation condition: if a run started or finished in the last 45 minutes, that run is returned instead with duplicate: true, and the force parameter overrides this. However, it never names an alternative sibling (e.g. run_status) or states when a caller should prefer inspecting an existing run over starting a new one.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return content (last run, recorded steps, stalled flag, schedule), which is important because there is no output schema. It stops short of describing formatting or freshness so it doesn't reach 5.

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; every clause (last run, steps, stall, schedule) contributes distinct information about what the caller receives.

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 parameters, no output schema, and rich annotations, the main burden is describing what comes back, which the description does comprehensively for a status tool. Minor gaps remain around the shape/format of the steps and schedule data, but nothing essential to invoking it correctly is absent.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. No parameter information is needed or missing.

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 ("Returns the last daily update run") and enumerates the payload (recorded steps, stall flag, schedule), which separates it from siblings like run_checkpoint, run_recap, and scan_status. However, it never names an alternative tool, so the differentiation is implicit rather than explicit.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative; the agent must infer that this is a read-only status check from the payload description alone. The closest sibling, run_recap, is not mentioned, so routing between them 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.

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered structurally. The description adds no behavioral context beyond the annotations (no rate limits, auth needs, or freshness semantics); its value is describing returned content, which belongs more to return-value coverage.

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. The trailing 'and how many are still open' lightly overlaps 'counts', but the sentence remains tight and readable.

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 only one optional parameter, the description carries the return-value burden and does name the reported fields (status, counts, open count, cell types). It could say more about what 'open' means, but it is adequate for a simple read-only status listing.

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% for the single optional 'brain' parameter (id or name, defaults to active brain). The description does not add any meaning beyond the schema, so the baseline 3 for full schema coverage 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 (Lists) and resource (brain's build cells of source and concept type) with what is reported (status, counts, open count). The tool name 'scan_status' and title 'Build cells' create a terminology mismatch, but the description itself makes the output scope unambiguous.

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 when-to-use, when-not-to-use, or alternative guidance is provided. A sibling like surface_scan could plausibly overlap, but the description never routes the agent to or away from it, leaving selection to inference.

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, idempotent, non-destructive, so the safety profile is covered. The description adds real value the annotations lack by disclosing the returned content (taskRef, timezone, cron, steps) and the last run start, which is important given there is no output schema.

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 that identifies the resource and its returned contents with no filler; every clause 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?

For a zero-parameter read tool with no output schema, the description adequately covers what is returned (the schedule record plus last run start). It stops short of describing the shape of 'steps' or any error/absence behavior, which slightly limits completeness.

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 field names in the description refer to return values rather than inputs, but with zero parameters there is nothing for the description to clarify on the input side.

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 ('Returns') and resource ('the recorded daily-update schedule') and enumerates the returned fields, so the agent distinguishes it from write-side siblings like schedule_set/schedule_register. It does not explicitly name those siblings, which keeps it just 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 read-only nature implies this is the inspection side of the schedule pair, so usage is inferable, but there is no explicit statement of when to call it versus schedule_register/schedule_set and no exclusions or preconditions.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — 'one task covers every brain' (scope of the registration) — and reinforces idempotency with 'or the existing task when one is already registered', which largely restates the annotation rather than extending it.

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 short sentences with no filler, and the primary return behavior is front-loaded. Slightly awkward run-on phrasing ('...client scheduler, or the existing task when one is already registered') but no wasted verbiage.

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, the description does explain what comes back (schedule + task prompt), which is helpful. However, it omits how this relates to schedule_get/schedule_set, whether calling it mutates any scheduler state, and what the agent should do with the returned prompt — gaps that matter for a 0-required-param tool whose name implies a write.

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% and both parameters (hour with a documented default of 7, and IANA timezone) are fully described in the schema. The description adds nothing about parameter meaning or interplay, 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?

The description does state a concrete outcome — returning a recommended daily schedule plus a suggested task prompt, or the already-registered task — but the verb 'returns' sits awkwardly against the tool name 'register', leaving it unclear whether this is a read or a registration action. It also never distinguishes itself from the closely named siblings schedule_get and schedule_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?

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternatives schedule_get and schedule_set. An agent cannot tell from this text why it would call schedule_register rather than schedule_get when it just wants to inspect the current schedule.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this overwrites state and is idempotent. The description reinforces the substitution ('Replaces the stored schedule') but adds little beyond the annotation, and does not say what is lost when replaced or whether the task must already exist.

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 compact sentence front-loads the action and key inputs, followed by the replacement behavior. Slight density for one sentence but no wasted text.

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 destructive, idempotent write with no output schema, the description informs the agent of the overwrite but omits validation prerequisites (does the recurring task have to pre-exist?), guidance on omitting optional fields (cron, steps, enabled), and return behavior. Adequate but with clear gaps.

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 60%; taskRef and timezone are documented in the schema, while cron, steps, and enabled are not. The description only restates taskRef and timezone and mentions cron/steps exist, without explaining format for cron or the effect of enabled, so it does not compensate for the coverage gap. Baseline 3 given partial schema documentation.

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 (records/replaces) and resource (stored schedule of the recurring daily-update task), and names the fields taskRef, timezone, cron, steps. It does not explicitly differentiate from siblings schedule_get and schedule_register, though the 'replaces the stored schedule' wording hints at a write vs. read/register distinction.

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 statement of when to use this vs schedule_register or schedule_get, and no prerequisites or exclusions. The phrase 'Replaces the stored schedule' implies an overwrite but does not tell the agent whether it should call schedule_get first or when registration is needed instead.

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 declare safety flags (readOnlyHint=false, non-idempotent, non-destructive); they say nothing about output. The description adds genuinely useful behavior: the link is single-use, it drives a passkey/recovery-key browser flow, and it degrades to a status response when nothing is pending. Missing are auth requirements and link expiry details, but the branching behavior is well disclosed.

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; the primary case (returning the link) precedes the fallback case (status). Every clause 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?

With no parameters and no output schema, the description carries the return-value burden and does so by describing both possible responses. The only gap is the absence of any routing guidance relative to the many sibling activation/brain tools.

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 zero parameters, so per the rubric the baseline is 4. There is no parameter surface the description needs to compensate for.

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 ('Returns') and resource ('single-use link' to finish securing the brain), and even covers the no-op branch ('the account's status if nothing is pending'). It is clearly distinct from siblings like activation_status or brain_current, though it never explicitly names or contrasts with 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?

The description explains what happens in each state but never says when an agent should call this tool versus alternatives such as activation_status or scan_status, nor any prerequisite (e.g., that the brain must be unsecured). Usage must be inferred from the name alone.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by stating the effect timing ('takes effect on their next request') and the scope of what is destroyed (ids, topics, or everything). It stops short of saying whether already-delivered memories can be recalled or what happens if the person has no active shares.

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 short sentences with no filler: scope and modes come first, the timing caveat second. Every clause carries information an agent needs.

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 four-parameter, destructive, no-output-schema tool, the description covers the operation, its granularities and its timing, and annotations carry the safety profile. Minor gaps remain around parameter interaction and whether revocation is reversible or retroactive.

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 50% (ids and concepts have no schema descriptions), so the description does real work by exposing the three revocation modes and mapping them to 'ids', 'topics' and 'everything'. It is weakened by not using the schema's term 'concepts' for topics and by not stating whether these parameters are mutually exclusive or how they combine.

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 (stops sharing) and resource (memories shared with one person), and enumerates the three revocation granularities (specific ids, whole topics, everything). An agent can tell this apart from share_with and shares_list by the inverse operation semantics, though neither sibling is named explicitly.

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?

Usage is implied rather than stated: the agent can infer this is the tool to call when sharing should end, and the granularity list hints at which parameter to pick. However, there is no guidance on checking existing shares first (shares_list), on precedence when several of ids/concepts/all are supplied, or on when to prefer revoking a topic vs individual ids.

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, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds genuine value by disclosing the two possible return shapes (a per-person count versus titles), which matters because there is no output schema; it says nothing about pagination or limits, keeping it from a 5.

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 compact sentence that front-loads the default behavior and then the parameter-conditioned variant. No filler, 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?

With no output schema, the description carries the return-value burden and does describe both output modes, plus it implies user-scoped authorization. Minor omissions remain (pagination, whether counts cover all share types), but an agent has enough to call 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 the baseline is 3, but the description goes beyond the schema's 'Name or email of a team member' by explaining the functional effect of supplying `person` — the result switches from counts to titles shared with that person. That is real semantic added 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 states a specific verb and resource ('Shows what the user currently shares') and scopes it to the authenticated user, which clearly separates it from share_with and share_revoke in the sibling list. It does not name those siblings explicitly, so it falls just 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 implicitly describes two usage modes (no argument = count per person; with `person` = titles shared with that person), which is enough to know how to call it. It never states when to prefer this over share_with, share_revoke, or team_list, so usage guidance remains inferred 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 only give the coarse profile (not read-only, not destructive, not idempotent); the description adds the two-phase preview/confirm gate and that shares are revocable and live, which is genuinely useful state-changing behavior. It stops short of covering permissions, re-share/additive behavior, or failure modes when the person is unknown.

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?

Three compact sentences, front-loaded with purpose, then the confirm gate, then reversibility. No filler and nothing repeated from 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 an 8-parameter mutation with no output schema, the description covers the key flow (preview then confirm) and reversibility, which is enough to call it correctly. It does not describe what the successful share response contains, but with no output schema declared that gap is minor.

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 already 88%, including the `confirm` token semantics, so the schema does the heavy lifting. The description reinforces the confirm/preview relationship and maps 'topics' vs 'memories' to the concept/ids parameters, but adds little syntax or format detail 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 with scope: 'Shares topics or specific memories with a member of the user's team (cloud-hosted brains)'. The parenthetical constrains where it applies, and 'live and revocable' implicitly distinguishes it from share_revoke without ambiguity.

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 procedural guidance: without `confirm` it previews and shares nothing, with the token it shares exactly the previewed scope. That is a clear condition for each mode. It does not name sibling alternatives such as share_revoke or shares_list, which keeps it short of a 5.

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 destructiveHint=true and idempotentHint=true. The description adds important context by clarifying that Engram does not connect to or read the source, and that it tracks when it was last read. However, it does not explicitly mention that this is a destructive or idempotent operation, which could be useful given the annotations. The added nuance is valuable but not fully comprehensive.

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 with zero waste, front-loading the core action and immediately clarifying the scope (does not connect/read) and tracking aspect. Efficient and well-structured.

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?

Given the complexity, annotations, and full schema coverage but no output schema, the description is mostly complete. It covers the key behavioral nuance (no actual connection), but could mention idempotency or destructive nature, though annotations already handle that. Overall, it provides sufficient context for an agent to call 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 schema already documents all parameters. The description provides examples like 'chat workspace, mailbox, drive or meeting recorder,' which aligns with the 'kind' parameter, but doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Records a source the brain is built from'), enumerates examples of source kinds, and distinguishes the tool from a data-ingestion tool by clarifying Engram does not connect to or read the source. This is clear enough to separate it from siblings like source_watermark on its own.

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 indicates this tool is for registering a source, implying when to use it, but it does not compare with alternatives like source_watermark or explain prerequisites. There is no explicit when/when-not guidance, so the usage is only inferred.

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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower. The description adds genuine behavioral context that annotations do not cover: that recording a failure feeds into a degraded-source flag in the daily plan. It does not, however, explain any permission, overwrite, or auth requirements.

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 tight sentences with the core action front-loaded and the downstream consequence second. Every sentence earns its place; nothing is padded.

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, the description still covers the purpose and the notable side effect (degraded flagging). For a five-parameter mutation tool it is largely complete, though it omits guidance on when in a run to call it and how watermark interacts with outcome.

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 all five parameters and the outcome enum. The description clarifies that the watermark may be a timestamp or cursor and ties the failure case to the outcome/errorClass fields, but adds only marginal meaning 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 states a specific verb+resource: recording how far a source has been read, including the failure case. This is clear and actionable, but it does not explicitly distinguish itself from nearby siblings like source_connect or scan_status, so an agent must infer the relationship.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The phrase 'failed this run' hints that this is part of a run workflow, but the agent is left to infer the timing and prerequisites on its own.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it marks passing memories 'at depth' and returns a gap listing on failure. It does not explain what 'closing' does to the cell's state or whether the destructive change is reversible, so it stays at 3.

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 dense sentence that front-loads the action and then gives the two outcome branches. No filler, though the compressed jargon costs some readability.

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, the description usefully describes the failure return ('lists each open memory with its gaps'), which is exactly the kind of information an agent needs and cannot get elsewhere. The main gap is the undefined semantics of 'closes'/'at depth', which are internal vocabulary.

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 four parameters are already documented, including memoryIds' 'omit to check every memory in the concept'. The description only restates that a cell is a source plus concept and echoes the whole-cell default, adding no syntax or format detail 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 ('closes the cell') and resource ('every memory in a cell (one source and concept)'), with the success and failure branches spelled out. It is distinguishable from stage_propose, though the domain jargon ('cell', 'marked at depth', 'saved as shallow') means an agent needs prior context to know exactly what is being closed.

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 conditional logic implies usage (run this to finalize a staged cell), but there is no explicit statement of when to call this versus stage_propose, nor any prerequisite that staging must happen first. Usage is inferable rather than 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 idempotentHint=true and destructiveHint=false, and 'Returns the existing cell if it is already open' largely restates that idempotency. The genuinely additive fact is the ordering constraint relative to memory writes, but there is no mention of permissions, cell lifecycle/closure, or error conditions.

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 action and scope, with no filler. The return-behavior note is placed last where it belongs.

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?

There is no output schema, and the description usefully states the return behavior for an already-open cell, which is the key return question. It omits auth/permission needs and the relationship to stage_commit, which would round it out for a mutation tool.

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 four parameters (brain, source, concept, entities) are already documented in the schema. The description only echoes the required 'source' and 'concept' pair and adds nothing about brain defaulting, entity shape, or limits.

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 concrete verb and resource ('Opens a build cell') and scopes it to exactly 'one source and one concept', with a gloss for the jargon term ('concept (topic)'). It does not name or differentiate against the obvious sibling stage_commit, which handles the staging lifecycle, so an agent must infer the relationship.

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 timing context: the cell is opened 'before its memories are written', which implies the correct position relative to memory_append/stage_commit. It also notes the already-open behavior. It stops short of explicit when-not-to-use guidance or naming 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 declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates state. The description adds genuine side-effect detail beyond that: it stores the measured size for the brain and starts the session's time box. It does not explain what makes the operation destructive or what prior state may be overwritten, leaving a notable gap against the 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?

Two sentences with no filler; the input contract is stated first and the return plus side effects follow. Nothing is redundant, though the phrasing is dense with project jargon ('first build', 'brain', 'time box') that adds no 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?

There is no output schema, so the description carries the return burden and does give a rough shape ('time-boxed plan with the coverage each tier reaches'), plus the write side effects. It stops short of describing the plan's structure or the relationship between tiers and coverage, which an agent would need to set expectations for the caller.

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 tier, brain, and the nested source fields are already fully documented in the schema, including the enum values and the 'about 20/40/60 min' mapping. The description only restates 'item count per source' and 'low, mid, high' without adding format or edge-case guidance. Baseline 3 is correct.

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 operation: it takes per-source item counts plus a depth tier and returns a time-boxed plan with per-tier coverage. That is a concrete verb+resource, not a restatement of the name. It does not, however, differentiate itself from adjacent siblings such as scan_status, run_start, or activation_stage, which an agent must disambiguate on its own.

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?

'Size the first build' and 'starts the session's time box' imply this is the sizing/planning step that precedes a scan session, which is usable context. But the description never states when to call this versus scan_status or run_start, and offers no exclusions or prerequisites. Usage is implied rather than 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes the content shape (roster plus per-direction share volume plus external sharers), but says nothing about auth requirements, scope limits, or freshness of the data.

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, boilerplate, or repetition of the title. Every clause adds a distinct piece of scope 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 zero-argument, read-only listing tool whose annotations fully cover the safety profile, the description gives enough to call it correctly. With no output schema, it could say a bit more about the return shape, but it already enumerates the three content buckets.

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 zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already communicates.

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 uses a specific verb ("Lists") and names three concrete things returned: team people, bidirectional sharing volume, and inbound sharers who aren't teammates. It is clear what the tool does, but it never distinguishes itself from the nearby sibling shares_list, whose territory (sharing relationships) it partially overlaps.

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?

"Lists the people on the user's team" implies the usage context well enough that an agent can infer this is the roster view, but there is no explicit when-to-use framing and no mention of alternatives such as shares_list or whoami for similar questions.

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 cover read-only, idempotent, closed-world, non-destructive semantics, so the bar is low. The description still adds real value by disclosing the conditional 'stale flag' behavior when topic memories changed after the summary was written — output semantics not derivable from 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 zero waste: what is returned comes first, the notable staleness caveat second.

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, two-parameter tool with no output schema, the description covers the essential return nuance (summary plus stale flag). It omits what happens when no summary exists and defers the brain default entirely to the schema, so it is strong but not exhaustive.

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% and the schema already documents both parameters (brain defaulting to the active brain, concept as the topic name). The description's '(concept)' restates what the schema says, so it adds little beyond the schema 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?

States a specific verb ('Returns') and resource ('the stored summary of one topic'), and the parenthetical '(concept)' maps user vocabulary to the parameter name. It implicitly distinguishes itself from the write-side sibling topic_summary_set by being a retrieval, but never names an alternative explicitly.

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?

Usage is only implied by the read verb — an agent can infer you call this to fetch a topic's summary, but the description gives no when-to-use guidance, prerequisites, or alternatives (e.g. recall, memory_search, topic_summary_set).

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 destructiveHint=true and idempotentHint=true, and the description reinforces the destructive aspect with 'replacing the previous one' — telling the agent existing content is overwritten. It adds the 1500-character constraint and the daily-plan context, though it says nothing about permissions or failure behavior.

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 tight sentences, front-loaded with the core action and constraint, with the usage context following. No wasted words.

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 tool with no output schema, the description plus annotations cover the essentials: what it does, that it overwrites, the size limit, and when to call it. It leaves the active-brain default behavior to the schema, which is acceptable.

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 (brain, concept, summary) are already documented. The description restates the 1500-character cap but adds no meaning beyond what the schema provides, 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+resource ('Writes the summary of one topic'), and the '(concept)' gloss plus 'replacing the previous one' make the write semantics unambiguous. It doesn't explicitly name the counterpart topic_summary_get, but the set/get naming and the write framing distinguish it adequately.

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 context for when to invoke it: 'Used for topics the daily plan lists as missing or out of date,' which ties the call to the daily_plan workflow. It stops short of naming an explicit alternative tool or stating when NOT to use it.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful return-content detail (brains, their ids/names/storage mode, and which is active), which is valuable given there is no output schema, though it says nothing about pagination or scoping when a brain is passed.

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, zero filler, with the return contents front-loaded and the usage cue second. Nothing is redundant with the title or schema.

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 present, the description correctly carries the return shape (account, brains, storage mode, active brain), which is adequate for a zero-required-param read tool. It is slightly incomplete in that the brain parameter's effect on the response (scoping to one brain) is not reflected in the stated return.

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 single optional brain parameter ('Brain id or name. Defaults to the active brain.') is fully documented in the schema. The description adds no extra semantics beyond that, 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 states a specific verb+resource: it returns the signed-in account, the list of brains with ids/names/storage mode, and the active brain. This is clearer than the title 'Account and brains', but it does not explicitly differentiate itself from siblings like brain_list or brain_current, which an agent may confuse it with.

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 concrete usage contexts: 'at the start of a conversation, or when you need a brain id.' That is clear when-to-use guidance, but it names no alternatives or exclusions (e.g., brain_current vs brain_list vs whoami), leaving the agent to infer which sibling to pick.

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