ctxstore — memory that follows you across models

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

Adds substantial behavior beyond annotations: email OTP mechanics, possible 402/503 responses, the fact that the code authorizes only the named grant_id, and the returned mcp_config header for header-based clients. This is exactly the kind of operational context annotations do not capture.

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 purpose, then gives a compact numbered flow with no wasted sentences. The docs link and mcp_config note are operationally useful rather than 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?

Complete for a two-step authentication tool with no output schema: it explains prerequisites, both steps, error conditions, scope limitation, and the next action. An agent has enough information to invoke it correctly without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description still adds useful semantic context, especially that the code activates the named grant_id only and authorizes nothing else, though most individual parameter details are already covered by 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: accept a namespace invitation for the authenticated account's verified email. It distinguishes the tool from siblings by naming list_invites as the source of grant_id and switch_workspace as the follow-up step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly defines the two-step flow with step='request' then step='confirm', including the specific conditions and likely error outcomes (402 needs Collaborator, 503 mailer failure). It also names the prerequisite sibling list_invites and the post-accept action switch_workspace.

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, and destructiveHint=false, so the write-once/idempotent/no-destroy profile is covered structurally. The description adds real value beyond that: persistence to mcp_sessions.agent_id (migration 0008), survival across setup_account(mode='restore'), and automatic re-hydration. It does not describe the return value, but the behavioral footprint 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?

The core action is front-loaded in the first sentence, with persistence, call timing, and clearing handled in short follow-on paragraphs. The migration-number citation is slightly gratuitous but overall every sentence 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 single-parameter, no-output-schema, annotation-covered tool, the description covers effect, lifetime, idempotency, and teardown thoroughly. Nothing an agent needs to bind identity correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents the empty-string clearing convention, which sets a baseline of 3. The description goes further, explaining the sticky-default behavior the parameter enables and that per-call override still works, adding real semantic meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Bind a sticky agent identity to this MCP session.' It also names the downstream consumers (wake_status, load_context) that read the binding, letting an agent distinguish this tool from those siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call ('once near the start of a session, ideally from your boot recipe'), states the exact no-op condition (re-binding the same agent_id), and documents the clearing path (agent_id=''). Override behavior of downstream calls is also spelled out.

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, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the server verifies the caller is the invitee via email/tenant match, and the invitation must still be pending. It stops short of saying what a successful decline returns or what error surfaces on a mismatch, hence a 4 rather than 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?

Three short clauses, front-loaded with the action and its precondition, with the alternative routing placed last where it belongs. No sentence is redundant or 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 single-param mutation with no output schema, the description supplies the operation semantics, the authorization check, and the sibling alternative. The only minor gap is the absence of any statement about failure modes (e.g., non-pending invitation, non-invitee caller), which annotations do not cover.

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?

With one parameter and 100% schema description coverage, the schema already fully documents grant_id as the UUID of the invitation. The description adds no syntax, format, or sourcing detail 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?

The description names a specific verb (Decline), the exact resource (a pending status=invited namespace invitation), and the actor role (as the grantee). It also distinguishes itself from the sibling revoke_grant by naming it as the grantor-side alternative, so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the precondition for use (the invitation must be pending, status=invited), restricts who may call it (the grantee), and explicitly routes grantors to revoke_grant instead. Both the 'when' and the 'when-not'/alternative are given, leaving little 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 destructiveHint=true and idempotentHint=true, but the description adds the crucial nuance that this is non-permanent: the fact is 'marked deleted but preserved' for audit and undo and 'excluded from all normal searches.' That materially changes how an agent reasons about the call beyond the safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded verb and resource, with each sentence carrying distinct information (soft-delete, preserved for audit/undo, search exclusion, usage trigger). 'Excluded from all normal searches' is slightly redundant with 'marked deleted' but still clarifies discoverability impact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation with full annotation coverage and no output schema, the description supplies everything an agent needs: reversibility, search impact, and the condition for use. Nothing relevant to correct invocation 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% and the single parameter already carries its own description ('The UUID of the fact to delete'). The description's 'by its UUID' adds no format or constraint detail beyond that, so the schema does the heavy lifting and 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 (soft-delete) and resource (stored fact) keyed by UUID, and the parenthetical 'Smart Forget' plus the soft-delete qualifier distinguishes it from a hard destructive delete. An agent can tell it apart from siblings like get_fact or move_fact 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?

'Use when information is no longer accurate or relevant' gives a clear triggering condition. It does not name alternatives or note when NOT to use it (e.g., undoing a prior deletion), so it stops short of explicit routing.

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 genuinely new behavior: retrieval is deterministic ('never misses') and returns only the current, non-deprecated version of the fact. That version-filtering behavior is not derivable from 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?

Front-loaded with the core purpose before the usage rationale. It is slightly dense with repeated examples, but every sentence carries information an agent needs to invoke it correctly, so little is wasted.

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 compensates by stating what is returned ('the current non-deprecated version'). It fully covers how and when to retrieve. Minor omission is whether a miss returns null vs an error, but overall it is complete for a single-key lookup.

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, but the description adds meaning beyond the schema's generic example by giving concrete key formats ('agent:<name>:self-note:opening') and stressing that the key must be an EXACT match for the deterministic path to work.

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 ('Retrieve a fact by its exact key') and immediately distinguishes itself from the two closest siblings, search_facts and get_fact_history, by emphasizing exact-key retrieval. The agent can tell this apart from its siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names when to use it (self-notes, inter-agent handoffs when the exact key is known) and when the alternative fails ('search_facts misses self-notes because their embedding similarity scores below other identity facts'). It even supplies the exact key patterns to call with, leaving nothing 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the returned payload is a list of versions and the ordering is newest to oldest, which matters because no output schema exists. Pagination/limit behavior is not mentioned, 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?

Three short sentences, each earning its place: purpose and payload composition first, then usage context, then return ordering. No redundancy and the most important information is front-loaded.

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 so by naming the payload shape and its ordering. Given a single required parameter, full schema coverage, and annotations covering safety and idempotency, an agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'key' parameter, with the schema itself supplying examples ('session-latest', 'current-stack'). The description only reinforces the notion of a 'keyed fact' and adds no format or syntax detail beyond the schema, 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 and resource (return the version history for a keyed fact) and defines scope precisely: current version plus all deprecated predecessors. This implicitly separates it from the sibling get_fact, but it never names that sibling, so the differentiation is inferred 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?

Gives two concrete use cases — seeing how a fact evolved over time and undoing an accidental correction — which is clear contextual guidance. It stops short of naming alternatives (e.g. 'for only the current value, use get_fact'), so no exclusion guidance is present.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's added value is freshness and cost semantics: 'Generated nightly and on session disconnect' tells the agent the result may be stale, and '~500 tokens' flags it as cheap. Return shape and any staleness guarantees are left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler: the payload description comes first, then the usage rule with its alternative. Every clause carries information the agent needs, including the token budget and generation cadence.

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 must fully characterize the return value, and it largely does (bio content, ~500 tokens, freshness cadence) and names the fallback tool. Minor gaps remain around whether the seed can be absent for a new tenant or how stale it can be.

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 schema makes no semantic demands and the description has nothing to disambiguate. Baseline of 4 applies; the description correctly adds nothing extraneous about inputs.

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 ('Return the pre-computed session seed'), then defines the artifact concretely ('a compact first-person bio (~500 tokens)'). It explicitly positions itself against a named sibling (load_context), so an agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection condition ('when you just need orientation') and names the alternative tool (load_context) as the heavyweight option. It does not spell out explicit exclusions or prerequisites, but the tradeoff implies when not to reach for 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by listing exactly which metrics are returned (storage totals, plan limits, collection sizes, daily query counts), which is useful since there is no output schema. It does not clarify scope (e.g., account vs workspace) or freshness, 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?

Two sentences, front-loaded with the tool's output content and then the usage trigger. Every clause adds distinct information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only tool with no output schema, the description supplies the key return categories and the reason to call it. It is nearly complete, though it could note whether the stats are scoped to the account, workspace, or agent.

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 per the scoring guidelines. There are no parameter semantics to add beyond the empty 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 ('Get your memory usage statistics') and enumerates the concrete metrics returned (total facts stored, plan limits, collection sizes, daily query counts). It clearly identifies the tool's scope, but does not explicitly differentiate itself from the sibling 'index_stats', which could be confused as another stats tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the trigger condition: 'Call this to check how much storage you have used and how close you are to your plan limits.' That is clear when-to-use guidance, though it offers no when-not-to-use or named 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?

Goes well beyond the annotations by disclosing the key non-obvious behavior: writes silently succeed but do NOT persist, which sibling tools are unaffected, and that the flag resets to off on session reconnect because it is not persisted. These are exactly the behavioral traits an agent needs and none are derivable from the schema or 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?

Three tight sentences, front-loaded with the action, then the effects, then the lifecycle caveat. No filler and every clause conveys actionable 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 one-boolean toggle with no output schema, the description covers everything needed: what it does, what it suppresses, what it leaves alone, and when it resets. Nothing required to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter is a single boolean, so the baseline is already met. The description adds real semantic content by spelling out the consequence of on=True versus the implicit off state, giving the parameter meaning beyond the schema's tautological 'True to enable ghost mode'.

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 pair (enable/disable), the resource (ghost mode), and its scope (this session). It also anchors the concept by naming the sibling tools it affects (store_fact, store_session_summary, search_facts), so an agent can place it immediately against the rest of the toolset.

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 makes the operational context clear: enabling ghost mode turns store_fact and store_session_summary into silent no-ops while reads keep working normally, which strongly implies a dry-run/do-not-persist scenario. It does not, however, give explicit 'use this when/do not use this when' phrasing or name an alternative tool for the same goal.

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, so safety is covered. The description adds genuinely new behavior beyond that: it exposes the visibility guarantee (recent writes always visible because ranking is bypassed) and enumerates the per-entry fields, which matters because no output schema exists.

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 sentences, front-loaded with the what and the when, with no filler. The trailing field-enumeration sentence is list-like but earns its place by standing in for the missing output 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, the description carries the return-shape burden and does so by naming the entry fields and the ordering guarantee; pagination is handled by the since_seq schema description. An agent has enough to call it correctly, though it never states a default or cost of a large limit.

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% — limit and since_seq are fully documented in the schema, including defaults, max, and pagination semantics. The description adds no parameter-level detail of its own, 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 (return recent fact operations) with scope (across all agents in this tenant) and ordering (newest first). It also distinguishes itself from the sibling index_search by noting it bypasses semantic search ranking, so an agent can route between the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger — 'Use this on session start to see what other agents wrote since you were last active' — which tells the agent exactly when this tool is the right pick over search_facts/search_context. It stops short of naming alternative tools or stating when not to use it, so it falls just 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the 'tenant activity index' framing and filter dimensions, with no pagination, ordering, or result-size behavior beyond the limit param.

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 plus a quoted example, with the core purpose front-loaded. The example earns its place by illustrating filter combinations, though it is slightly redundant with the preceding enumeration.

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, idempotent search tool with a fully documented schema and no required params, the description supplies purpose and a use scenario. Return ordering/pagination nuances are not covered, but the absence of an output schema and the strong annotation coverage keep this near-complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter is already documented in the schema; baseline 3 applies. The description's example implicitly shows how agent_name, namespace, and op combine, but adds 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+resource ('filtered search over the tenant activity index') and enumerates the search dimensions (agent, namespace, create/update/delete). An agent can tell it is a search tool, but it does not explicitly differentiate it from siblings like index_recent or search_facts.

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 coordination scenario ('what did emily_dev store in the sprint namespace today?') gives a concrete when-to-use signal. However, no alternatives are named and there is no when-not guidance versus index_recent, index_stats, or search_context.

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 and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond them by naming what the aggregated data actually contains (per-agent, per-namespace, per-day breakdowns), though it omits cost, freshness, or time-window 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?

A single efficient sentence, front-loading the data source before the breakdown list. The trailing 'and where' is mildly vague filler but the whole thing is compact with no wasted sentences.

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 returns and does so reasonably via the breakdown list. What is missing is sibling differentiation from get_stats and any scoping/freshness note, which keeps it short of full 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 zero parameters, which is the baseline-4 case; the description correctly does not invent parameter talk. One caveat: with no parameters, the scope of the statistics (which tenant, what time range) is fixed by the server and is never stated.

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 clear resource — usage statistics from the tenant activity index — and enumerates the aggregation dimensions (total operations, by agent, by namespace, by day). An agent knows what it gets, but the description never distinguishes it from the sibling get_stats, which is the most likely confusion.

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 closing phrase 'useful for understanding which agents are most active and where' implies a usage context but gives no when/when-not guidance and no routing against get_stats, index_recent, or index_search. 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds genuine behavioral context beyond that by disclosing the exact write target (category=identity, namespace=shared/agent-feedback, key=intro:<model>-<date>), which also explains why the operation is idempotent within a day. It does not describe the response, but the storage disclosure is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and optionality, then the storage shape, then the content guidance. Every line earns its place and there is no redundant 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?

No output schema exists, but the description covers what is stored (model info + note), where it is stored, and what to include, which is sufficient for a simple write tool. The only minor gap is return/confirmation behavior, which is not critical for this optional self-registration call.

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 three parameters, including examples for model and platform. The description reinforces the intent ('what model you are, what platform you're running on') but adds no format or syntax detail beyond the schema, making the baseline 3 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+resource ('introduce yourself to the platform') and immediately clarifies the effect: it stores model info and a note in the shared agent registry. It further distinguishes itself from store_fact by revealing the fixed category/namespace/key pattern it writes to, so an agent can tell it apart from the generic fact-storage siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Flags the tool as 'Optional' and hints at first-connect usage ('anything you noticed on first connect'), which gives implicit context. However, it never states when to prefer this over store_fact, nor any when-not conditions or prerequisites, leaving the routing decision largely 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 only give the safety/idempotency profile; the description goes well beyond: nothing is shared until acceptance, repeat calls return the existing invitation with no second email, an email is sent on acceptance, and list_workspaces reveals whether the invitee has joined. It also discloses the billing consequence (30 days free, then $19/30 days) that an agent might otherwise trigger unknowingly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and consequences; nearly every sentence carries operational value (idempotency, withdrawal, exclusion, acceptance visibility). Somewhat dense as a single block, and the pricing sentence plus docs link are the least essential parts, but nothing is wasted.

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 mutating, email-sending, idempotent tool with no output schema, the description covers the effect, the pending-state semantics, idempotency, how to undo, side effects, and how acceptance is observable. An agent has everything needed to call it and predict the 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 coverage is 100%, so email, namespace_prefix, and note are already documented with their constraints and examples. The description reinforces that the prefix is read-write and per-account but adds no syntax or format detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (invite), actor scope (one person, by email), resource (namespace prefix of THIS account) with a concrete example (project:barn). It is clearly distinguishable from siblings like list_invites, accept_invite, and revoke_grant, which are named in their respective roles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes the follow-up flow on the recipient's side (list_invites and accept_invite), the withdrawal path (revoke_grant with grant_id), and a hard exclusion: not available from a shared workspace session. Named alternatives plus a when-not condition.

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 genuine extra context: it is a self-service grantee action and the server verifies grantee authorization, which implies a permission precondition not expressed in the schema. It stops short of describing what the grantee loses (e.g., retained fact data or re-access options), so it is not fully complete.

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 action and effect, then precondition, then the disambiguation to the sibling tool. Every sentence earns its place with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description covers action, actor, authorization verification, and the boundary with revoke_grant, while annotations cover destructiveness and idempotency. The main gap is the post-condition for the grantee (what access or data is affected after leaving), which is left 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?

There is a single parameter with 100% schema description coverage ('UUID of the active grant to leave'), so the schema already carries the semantics. The description adds no format, sourcing, or lookup guidance for grant_id beyond what the schema states, making the baseline 3 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+resource ('Leave an active namespace grant') plus the role it acts as (the grantee) and the effect (stop using shared namespace). It also explicitly distinguishes itself from the sibling revoke_grant, so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('as the grantee... stop using shared namespace') and when-not-to-use with a named alternative ('Grantors who want to cut off a collaborator must use revoke_grant'). No inference is required to pick between the two tools.

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 safety, so the safety burden is covered. The description adds real behavioral context beyond them: deterministic vs semantic matching, newest-first ordering, the default limit of 50, and the returned field set. Does not cover pagination beyond limit or rate behavior, but that is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the one-line purpose and the sibling distinction, then examples. Every block earns its place, though the three examples plus the return-field sentence make it longer than strictly minimal; nothing is redundant or 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?

No output schema exists, so the description carries the return-shape burden and does so by listing the returned fields and ordering. Combined with the parameter guidance and routing to search_facts, 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%, so baseline is 3, but the description goes further by showing concrete prefix syntax ('comms:<agent-id>:', 'chad:trio:', 'conventions/') and the intended feeding of since_epoch via last-wake-epoch. That meaning is not present in the raw schema strings.

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 (deterministic prefix scan over fact keys) with the scope constraint (optionally bounded by timestamp). Explicitly distinguishes itself from the sibling search_facts by explaining that the semantic search 'misses exact-key facts'. An agent can route between the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names concrete use cases (R1 comms scans, dispatch discovery, trio listings, convention discovery) and the governing rule ('any case where you know the key prefix and want every match'). Names the alternative search_facts and the condition that selects against it, and reinforces with three worked examples.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), yet the description adds substantial context: it is a server-side authoritative list, rows carry status invited|active|revoked, verification requires matching grant_id plus namespace_prefix plus grantor, and the downstream accept flow costs 30 free days then $19/30 days with a 402 on lapse. That is behavior an agent could not infer from the annotations or empty 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?

The core scope and return fields are front-loaded in the first sentence, with verification and follow-up acts after. The pricing/402 detail and the docs URL are somewhat tangential to a read-only listing tool and arguably belong with accept_invite, so the last paragraph is slightly over-weighted.

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 must explain return values, and it does so with a concrete field list and enum values. It also covers the verification question and the next step after listing, leaving nothing essential for a correct call 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?

The tool takes zero parameters, which is the baseline-4 case, and the description correctly spends no words on arguments. It instead describes the output row shape, which is the only semantic surface available here.

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 and resource ('List this account's namespace collaboration grants: incoming invitations and outgoing shares') and immediately enumerates the row fields, so an agent knows exactly what comes back. It is clearly distinct from invite, accept_invite, decline_invite, and revoke_grant, which mutate the same objects.

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 trigger case ('An invitation referenced anywhere else ... can be checked against this server-side list') and routes the agent to accept_invite and switch_workspace for the follow-up flow. It stops short of stating an explicit exclusion, such as when to prefer list_workspaces or get_stats instead, but the usage context is clear.

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 free; the description adds genuinely new behavior: ordering ('newest activity first'), the project:<slug>:* naming convention, and that the current-workspace field appears only 'if any'. It stops short of describing the shape of the shared_by_you records or ordering for granted workspaces.

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?

Every sentence carries real information, but the opening is a long triple-clause construction loaded with nested parentheticals, and the usage guidance is buried at the end. Leading with the verb and the three return buckets would make it far more scannable.

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 no parameters, the description must carry the return shape alone, and it does: three result groups plus a conditional current-workspace field. Ordering for the granted-workspaces and shared_by_you sections is unspecified, a minor omission for a read-only list.

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 is 4. The description still supplies the key-prefix convention that governs the project entries and clarifies the grantor-name argument used by the sibling switch_workspace, which is extra context rather than schema repetition.

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 enumerates exactly what the call yields: own projects keyed by project:<slug>:*, workspaces granted by others, and shared_by_you invitee status, plus the current session workspace. That is unambiguous for an enumeration tool and rules out write siblings like switch_workspace, though it opens with a noun phrase ('The places...') rather than a verb, so the action itself is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Three concrete triggers are given ('request is about one project', 'asks who has access', 'whether an invitee came in'), and it explicitly routes the agent to switch_workspace(name=<grantor>) for entering a workspace. The gap is list_invites: the invitee-status content here overlaps that sibling and the description never says which to prefer.

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 behavioral context beyond that: deterministic layer composition, a single-round-trip merged bundle for profile recipes, and the profile boot algorithm (read pointer, parse LOAD/REQUIRE/HANDLER, fetch named facts). It does not restate truncation/caching limits, which live in the 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?

Front-loaded with the core behavior and structured into default-load, then profile-recipe usage. It is dense and slightly long, but for a 10-parameter tool with no output schema nearly every sentence carries load; minor redundancy with the schema's own parameter prose.

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 correctly explains what comes back (layered memory and merged bundles). It covers the default and profile flows well, but omits mention of the section-expansion and hint flows, which an agent must discover from parameter descriptions.

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 meaningfully supplements it: profile semantics (server reads platform:profile:<profile>:current, follows the pointer, merges results) and vars supplying $TASK_FACT_KEY-style recipe variables are not obvious from the schema alone.

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 ('Load your bootstrap context') and decomposes exactly what is loaded (L0 identity, L1 architecture, L2 state, L3 session summary). It also distinguishes itself from the sibling search_facts, so an agent can tell it apart without opening another 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?

'Call this at the START of a new session as an alternative to manual search_facts calls' gives explicit timing and names the alternative it replaces. It does not state when NOT to use it (e.g. mid-session refreshes vs. targeted get_fact), so it falls short of full routing 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?

Discloses behavior well beyond the annotations: max 1.4x boost, ~6-hour half-life, a global cap on stacked boosts, and the important safety guarantee that salience is ranking-only and cannot override tenant isolation, namespace grants, or privacy filters. This is context annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then decay behavior, then the sibling distinction, then usage constraint. Dense but every sentence carries a distinct, decision-relevant fact 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?

No output schema exists, but for a ranking-marking operation the description supplies the full picture an agent needs: decay semantics, caps, safety limits, and required input. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already fully documented; the description's 'Name the current situation in reason' and its weight guidance largely restate what the schema provides. 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?

States a specific action (temporarily boost a fact's retrieval ranking) with a concrete mechanism (salience peptide) and immediately contrasts it with the sibling reinforce_fact. An agent can distinguish this from other fact tools without opening any 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 explicit when-to-use triggers (approaching deadline, live incident, topic under active work) and names the alternative, reinforce_fact, along with the timescale distinction that selects between them (hours vs. weeks). Nothing 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 establish idempotent=true, destructive=false, readOnly=false. The description adds substantial behavioral context beyond that: it updates metadata in place, preserves fact_id, text, embedding, timestamp, and the deprecation chain, and explicitly avoids storage bloat. This is exactly the kind of mutation semantics the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action, then the invariants, then the use case. No filler — every clause carries distinct 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 non-destructive, idempotent mutation with a fully documented schema, the description covers action, invariants, and motivation. The only omission is what the call returns or whether it reports confirmation, which is minor given there is 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%, so fact_id, new_layer (with layer enum semantics), and new_namespace are already fully documented. The description names namespace and layer conceptually but adds no format, default, or validation detail beyond the schema. 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?

The description states a specific verb+resource ('Move a fact') and pins down the scope ('to a different namespace or layer without changing its content'). This cleanly separates it from siblings like store_fact, delete_fact, and get_fact without needing to open 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?

It gives an explicit use case ('reclassifying facts, e.g. bootstrap-v2 refactor') and contrasts the alternative pattern ('store-new + soft-delete-old'), telling the agent when this is preferable. It stops short of naming the actual sibling tools or stating hard 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?

Goes well beyond the annotations by disclosing the reward mechanics (bounded, time-decaying multiplier, max 1.5x, 14-day half-life) and, critically, the safety ceiling: the boost is ranking-only and cannot override tenant isolation, namespace grants, or privacy filters. Annotations merely say non-readonly/non-destructive/non-idempotent; the description explains the actual effect and its 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?

Front-loaded with the purpose and mechanism, then the timing rule and safety constraint. The 'Reward peptide' flourish and parenthetical examples cost a little, but each sentence carries operational content.

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 must carry the return/effect semantics, and it does: it explains exactly what the call changes (a bounded ranking multiplier) and what it cannot change. Timing, safety, and effect are all covered for this 4-param 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 key, fact_id, reason, and weight are already fully documented in the schema. The description reinforces the reason requirement and the outcome-tracing intent but adds no syntax or semantics beyond what the schema states, 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 ('reinforce a fact') and immediately distinguishes it from similarity-based siblings by scoping it to facts whose recall led to a confirmed good outcome. The 'recall-on-success' framing makes it unambiguous versus mark_salient or store_fact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to call ('AFTER the outcome is confirmed') and when not to ('never for a fact that merely seemed relevant'), with a concrete trigger list (fix worked, deploy green, user approved). This is the rare case of genuine when/when-not 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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavior beyond that: it does not say whether resuming mutates server state (note readOnlyHint=false despite the 'load' framing), what is returned, or what happens when no prior session exists.

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 clauses with no padding, so it is terse, but the second fragment ('Last session: no prior session') reads as an injected dynamic value rather than usable instruction and creates more confusion than clarity without context.

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 no parameters, so the description carries the full burden of explaining what resuming actually yields — and it does not. For a zero-arg stateful session tool sitting among several similar siblings, an agent is left guessing about both selection and result.

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. Baseline 4 applies; no parameter-level information is 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?

The verb 'load' and object 'session continuity' are stated, but 'session continuity' is abstract and never concretized. Nothing separates this from close siblings such as get_session_seed, load_context, or wake_status, so an agent cannot tell which one to pick 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?

'Call to load session continuity' at best implies it belongs at session start, but there is no explicit when-to-use statement, no when-not, and no named alternative among the many context/session siblings. Routing must be inferred entirely.

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 'Idempotent' in the description adds no new information. What the description does add beyond the structured fields is the authorization requirement — the caller must be the grantor/namespace owner — which is real behavioral context an agent needs before invoking. It does not say what happens to the namespace or grantee state after revocation, which keeps it short of 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?

Three terse sentences with the role constraint front-loaded, followed by the idempotency note and the alternative-tool routing. Nothing is padded and no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-output-schema tool with rich annotations, the description covers scope, authorization role, idempotency, and alternatives. It leaves unspecified what a failed revocation by a non-owner looks like, but that gap is minor at this complexity level.

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 parameter ('UUID of the grant to revoke'), so the schema carries the full parameter burden. The description adds no format, sourcing, or lookup guidance for grant_id, making the baseline 3 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 (revoke) and resource (pending invitation or active grant) plus the actor role ('as the GRANTOR (owner of the shared namespace)'), which immediately distinguishes it from sibling grant/invite tools like decline_invite and leave_grant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the caller: grantors use this tool, while 'Grantees use decline_invite / leave_grant.' The condition that selects this tool versus its siblings is stated outright rather than 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description clarifies the corpus it searches (conversations and session history) but adds nothing about result ranking, pagination, or result shape, and there is no output schema to cover that 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 sentences, zero filler. The scope statement comes first and the usage guidance follows immediately, making it easy for an agent to parse.

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 should ideally hint at what search returns (ranking, snippet format, pagination), and it does not. Coverage of purpose and parameters is adequate, but the missing return-value context leaves a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so query, top_k, source, and days_back are fully documented in the schema with defaults, ranges, and enum values. The description adds no parameter-level guidance beyond the schema, which meets the baseline for high coverage.

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: search across ingested conversations and session history. It implicitly distinguishes itself from fact-based siblings by targeting 'context that wasn't explicitly stored as a fact', though it never names search_facts directly.

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 a clear context for use (finding discussions, decisions made in conversation, or context not stored as a fact), which effectively routes the agent away from search_facts. It stops short of an explicit 'use X instead when...' exclusion statement.

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 without the description. The description's behavioral additions are thin: it discloses namespace prefix-matching semantics, but the RECOLLECTIONS/recent-fact augmentation behavior is already spelled out in the schema's recollect and boost_recent descriptions.

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 routing decision before the mechanics and breaks the rest into short scannable blocks (namespace scoping, search tips). It is slightly longer than strictly necessary and omits any mention of recollect/boost_recent, so effort is spent unevenly across the parameter set.

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 7-parameter, 1-required retrieval tool with no output schema and full schema coverage, the description supplies the missing routing context (when not to use it), namespace semantics and search strategy. There is no output schema to explain, and the output-shaping flags are documented in the schema, so nothing essential is left unstated.

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 a 3 is the floor and the schema already documents all seven parameters including the layer enum and the recollect/boost_recent toggles. The description goes slightly beyond that by explaining that namespace uses prefix matching ('webapp' matches 'webapp/decisions'), which the schema's one-line 'Filter results to a specific namespace' does not convey.

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 ('Search your persistent memory for stored facts') and explicitly separates itself from the deterministic bootstrap siblings load_context() and wake_status(). An agent can route between semantic discovery and deterministic retrieval without opening any 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 explicit when-to-use ('when you need semantic discovery across the fact corpus') and when-to-prefer-alternatives ('For session bootstrap, prefer load_context() or wake_status()'). It even adds query-construction guidance ('use the words the fact was stored with'), which is unusually actionable.

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 substantial context beyond the annotations: it explains the server's new-vs-returning branching, that it produces no duplicate/orphan accounts, that session IDs rotate between requests (forcing email= on verify and reveal_key), that reveal_key success responses only return a fingerprint, and that callers proving neither session nor email ownership are refused. None of this is in the annotations, which only convey the coarse read/write/destructive/idempotent profile.

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 primary path and organizes the rest mode-by-mode, which suits an 8-value enum. It is somewhat long and the session-rotation caveat is repeated across the verify and reveal_key paragraphs, which is minor redundancy a tighter edit could remove.

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 stateful, multi-mode auth tool with no output schema, the description covers the full flow: initial call shape, OTP confirmation step, restore path, key reveal, and the post-setup action. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining *why* email must be passed on verify (session ID rotation on some clients) and by disambiguating the mode enum with concrete call examples such as setup_account(mode='link_or_create', email='...'). This adds reasoning the schema's terse enum description does not.

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 ('Set up or restore your persistent memory connection') and immediately enumerates the concrete modes with their triggers. An agent can distinguish this from siblings like resume_session, get_session_seed, and bind_agent (which it explicitly notes is subsumed by the agent_id param) 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 explicit when-to-use routing for each mode: 'link_or_create' when the user supplies an email, 'restore' when the user has an emk_* key, 'reveal_key' only when the full key is genuinely needed. It also names the alternative path (bind_agent via agent_id) and prescribes the follow-up action (call search_facts first).

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 this is a non-read-only, non-destructive, non-idempotent write, so safety is covered. The description adds real behavioral context beyond that: same-key writes auto-archive the prior version, namespaces organize facts, and the layer system encodes decay horizons. It does not mention workspace scoping or what the call returns, so it is not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in a single sentence, then organized into scannable bullets that each carry a distinct tip. It is somewhat long, and a few bullets restate enum lists already present in the schema descriptions (category, layer), which is the main source of 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 7 parameters, rich annotations, and no output schema, the description covers the semantics an agent needs to store a fact well. It omits two things that matter for a write tool: whether the call returns a fact UUID or key, and whether facts are workspace-scoped (relevant given switch_workspace and list_workspaces siblings).

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 meaningfully extends parameter meaning by showing how to phrase searchable text, when to use key (facts that change over time), and concrete namespace/layer/category conventions with examples. The duplication of the category and layer enumerations found in the schema slightly blunts the 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?

States a specific verb and resource with scope: 'Store information that should persist across sessions.' It is clearly distinguishable from read/delete siblings like get_fact and delete_fact. However, it never differentiates itself from the very similar sibling 'store_facts' (plural), leaving the agent to guess which of the two write tools 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?

Gives concrete when-to-store guidance (decisions and context, not raw data) and explicitly routes the agent to store_session_summary before ending a conversation, which is a named alternative for a specific condition. It stops short of stating when NOT to use this tool or how it differs from store_facts.

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=false), so the description's added value is the per-item write semantics: 'Each item is stored independently; the reply lists what landed and what did not,' which warns the agent about partial success. It stops short of stating auth requirements or duplicate handling.

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 sentences, front-loaded with the batch limit and batching rationale before the memory-portability motivation. Dense but every clause is doing work; the parenthetical platform list is slightly long but justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing the reply ('lists what landed and what did not'). It covers the primary migration use case well, but leaves an agent guessing on category/layer/namespace semantics for a tool whose schema is undocumented.

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 0%, so the description must carry the item-level semantics, and it only partly does: it implies 'text', 'one fact per item', and a date-learned field (which does not actually exist in the schema). The enum values for category, plus key, layer, namespace and is_permanent, are left entirely 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 and scope ('Store up to 50 facts in one call') and explicitly distinguishes itself from the sibling store_fact by noting it takes 'the same fields as store_fact per item'. An agent can tell the batch variant from the single-fact variant without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete when-to-use scenario: 'when you already remember things about the person from your own platform memory (ChatGPT memory, Claude memory, Gemini saved info), write them here.' Clear context, though it never states the converse (when to prefer store_fact or delete_fact instead), so no explicit 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?

With annotations already covering the safety profile (readOnly=false, destructive=false, idempotent=false), the description adds real value: it discloses that storing auto-archives the previous version (explaining the non-idempotent behavior), the key naming scheme, and that the next session retrieves it via load_context(). It does not describe failure modes or what happens on first-ever store, so not 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?

Core purpose and the 'call before ending a conversation' directive are front-loaded in the first two lines. The multi-sentence collaborative-takeaway paragraph with an inline example is genuinely useful usage protocol but is longer than the tool description strictly needs, adding some bulk.

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 non-idempotent mutation tool with 6 params, one required, and no output schema, the description covers purpose, timing, content guidance, storage/archive lifecycle, and cross-session retrieval. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. 'Include: what was discussed/decided, what changed, what's next/unresolved' loosely maps to summary/decisions/next_steps but largely repeats the schema's own descriptions, and the more cryptic params ('scope' watermark, 'contributors' attribution) are not clarified 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 (store a compressed summary of this session) and names the exact storage mechanism: an L3 session fact keyed 'session-latest'. It clearly distinguishes itself from the generic store_fact/store_facts siblings by tying the write to the session lifecycle and naming load_context() as its consumer.

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?

Explicit when-to-use: 'Call this before ending a conversation', plus concrete trigger signals ('okay I'm out', 'let's wrap', 'bye') and a confirm-before-storing protocol with a worked example. The alternative path (arbitrary facts via store_fact) is implicitly excluded by scoping this to session-end continuity.

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?

Beyond the annotations (readOnly=false, idempotent=true, non-destructive), the description discloses stickiness for the session, persistence across reconnects, that the narrowed bundle is returned immediately, that identity/conventions always ride along, and that bind_agent is unaffected. These are non-obvious behavioral traits an agent could not infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary use case and scoped effect before the shared-workspace variant. Slightly redundant on session stickiness ("Sticky for the session and across reconnects" partially repeats "it holds for the session"), which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter session-mutating tool with no output schema, the description covers return behavior, session/reconnect persistence, interaction with bind_agent, and the enter/leave lifecycle. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining what each value does downstream (project:<slug>:* scoping, tenant id / granted prefix accepted, '' widens or leaves). This gives the single parameter operational consequences, not just a type.

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 opening sentence states a specific verb and effect ("Narrow this session's memory to one project") and spells out exactly what gets scoped: recall, wake bundle, self-notes, and the default namespace. It is clearly distinguishable from siblings like list_workspaces and bind_agent, which it names.

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?

Explicit when-to-use instructions are given for each mode: slug to narrow, '' to widen/leave, granted name to enter a shared workspace. It also names the routing condition ("When a person asks to work in someone else's shared memory, call this") and the boundary against bind_agent.

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 description focuses on behavior the annotations can't convey: the layered return shape, the missing[] diagnostic list, the is_fresh_agent=true signal for brand-new agents, and the account-level warning when agent_id is omitted. It does not mention rate limits or auth requirements, but the added context is substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return shape, then a second paragraph for the optional profile mode. Two paragraphs for four parameters is proportionate, though the second paragraph is dense and could be trimmed slightly.

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, and it does: layer-by-layer found status, missing[], is_fresh_agent, and the account-level warning. Behavior across the optional profile path is also covered. Minor gap: it doesn't say how vars substitutions interact with the reported status.

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 structured fields already document vars, scope, profile, and agent_id thoroughly. The description still adds value by explaining the consequence of profile (REQUIRE keys fold into missing[]) and framing the whole call as a verification step, going beyond a restatement of 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: reporting which context layers (embryo, conventions, identity, closing note, opening note) loaded at session start, plus a missing[] list. This is clearly distinguishable from load_context/resume_session, which perform the bootstrap rather than verify it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call it: 'after load_context() or resume_session() to verify your bootstrap was complete and diagnose what to fetch manually.' It also names the condition for the optional profile mode (validating REQUIRE keys for a given recipe), so the agent knows both the trigger and the alternative modes.

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 safety (readOnly, idempotent, non-destructive), but the description adds substantial context beyond them: max wait of 25s, up to 50 events returned plus next_since, server retention of ~10000 events per account, and workspace read-grant filtering of keys. This is the kind of operational behavior an agent needs and can't infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core mechanic and the no-streaming loop constraint, then examples. Dense but every sentence carries information (event shape, retention, cursor semantics) and nothing is redundant 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 carries the return burden and does so: event fields, the 50-event cap, and next_since are all explained. An agent can loop correctly and avoid missed events from this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: since=0 replays retained events, a bare integer N returns seq > N, and next_since is the resume cursor to feed back. It reinforces and slightly extends the schema rather than merely 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?

States a specific verb and resource ('Long-poll this account's fact-write events') and explicitly distinguishes itself from the re-scan pattern ('instead of re-scanning with since_epoch'). The event enumeration and returned shape make the 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?

Gives the when-to-use (instead of re-scanning), the exact loop pattern to follow because 'MCP has no streaming here', and names an alternative for long-lived clients (GET /api/v1/events SSE). Two concrete examples cover the common wait and resume cases.

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