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

Annotations only declare the generic mutation profile (readOnly=false, destructiveHint=false, idempotent=false). The description adds real behavioral context beyond that: the pending_supersedes proposal flow waits for Owner review in every approval mode, the old decision stays in effect until approval, and version errors (version_required/version_conflict) cause zero writes. It does not state duplicate-handling or auth requirements, keeping it below 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?

Content is front-loaded (lifecycle and purpose first) and each point is substantive, but the entire description is duplicated verbatim in Chinese and English, roughly doubling length without adding information. The Args block is also long for a 13-param tool.

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

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

For a 13-param mutation tool with annotations and an output schema, the description covers the decision lifecycle, the supersedes approval semantics, and nearly all parameters. It leaves project_folder and user_confirmed (which may be safety-relevant, e.g. user confirmation) unexplained, which is the main remaining 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 0%, so the description carries the parameter burden, and it does document 11 of 13 params including the critical supersedes/supersedes_expected_version coupling and its failure modes. Two schema params, project_folder and user_confirmed, are never mentioned, so the coverage is strong but incomplete.

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 ('record one key decision') plus the exact trigger ('when the user explicitly chose an option', with quoted examples like 'we decided to use X'). It also names the sibling it is not (extract_session_insights) for the summary-extraction case, so an agent can route without opening schemas.

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

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

Explicit when-to-call (explicit decision made in conversation), explicit when-not (user supplies a session summary → use extract_session_insights), and it spells out the alternative approval path via the supersedes decision thread. 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?

Goes far beyond the annotations by disclosing the write pipeline's consequences: similar summaries are linked as related rather than rejected, normalized-identical content is refused with a pointer to the existing entry, supersedes always creates a pending proposal requiring Owner approval, owner-pinned lessons can only be revised via supersedes, and version mismatch produces version_conflict with zero writes. These are exactly the non-obvious mutation semantics an agent must know before calling.

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 and well sectioned (lifecycle, purpose, note, args), and each individual sentence earns its place. However, every sentence is duplicated verbatim in Chinese and English, roughly doubling the token cost with zero added information for a given reader. The arg list is also long relative to what a caller needs at invocation time.

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?

A 13-parameter mutation tool with an output schema and non-trivial dedup/versioning semantics, and the description covers the routing, dedup policy, revision protocol, and failure modes. Only the two undocumented parameters (project_folder, user_confirmed) leave a gap in what an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: 11 of 13 parameters get meaning, format hints (comma-separated domains, ISO-8601 timestamps, tool names like 'claude_code'), defaults, and even failure modes (version_required, version_conflict). Two parameters are never mentioned — project_folder and user_confirmed — leaving an agent to guess their effect on write behavior.

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 (record a single lesson learned) and qualifies the input state ('when you already know what to save'), which distinguishes it from the extraction sibling. It also enumerates the trigger kinds (lesson, pitfall, technical finding). It does not distinguish itself from other writing siblings such as add_decision, add_playbook, or memory_store, which share the same 'write a knowledge artifact' space.

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 positive condition ('call when the user explicitly states a lesson, pitfall, or technical finding') plus an explicit exclusion naming the alternative tool and the scenario that selects it (session summary → extract_session_insights). That is exactly the when/when-not/alternative routing an agent needs.

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, closed-world mutation, but the description adds substantial workflow context. It explains that each playbook is stored as an individual file, retrievable via trigger keywords, and that MCP writes always enter a review queue until the Owner approves. It also documents revision behavior, version conflicts, zero-write failure modes, and pinned-playbook restrictions, which are valuable beyond the annotations.

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

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

The information is front-loaded with purpose and usage before the argument list, which helps. However, the bilingual duplication roughly doubles the length, and the description repeats concepts already available in the structured review workflow. For a 20-parameter tool the detail is warranted, but the presentation is more verbose than necessary.

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

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

Given the complexity of 20 parameters, the approval workflow, and the existence of an output schema, the description covers the essential purpose, storage model, review behavior, revision semantics, and most caller-facing parameters. It leaves several optional or internal-looking parameters undocumented, such as run_id, scope_type, source_agent, project_folder, user_confirmed, and last_validated_at. Output values need not be explained because an output schema exists.

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 parameter meaning. It documents most parameters with examples and semantics, including title, triggers, steps_json, required_tools_json, tool_refs, description, domain, preconditions, pitfalls, outcome, source_tool, allow_similar_new, supersedes, and supersedes_expected_version. It omits some parameters such as run_id, scope_type, source_agent, project_folder, user_confirmed, and last_validated_at, so it is not fully complete.

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 clearly states a specific verb and resource: record an operational playbook as a structured multi-step procedure. It gives concrete examples such as publishing to a registry or app deployment. It does not explicitly distinguish itself from siblings like add_lesson or add_decision, so it falls short of a 5.

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

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

The description gives a clear usage condition: after completing a multi-step operational process, record the steps for future retrieval and reuse. It does not name alternative tools or state when not to use this tool versus siblings such as add_lesson, add_decision, or memory_store. The guidance is strong but lacks explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds what the check actually inspects ('data fragmentation, stale knowledge, conflicting decisions, identity issues'), which is genuine context beyond the annotations. It doesn't describe report shape or runtime cost, but the output schema exists for that.

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, then use case, then parameters — a clean shape. It is roughly doubled in length because every sentence is given in both Chinese and English, which is wasteful for a single-locale reader but consistent and still 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 an output schema present the description needn't document return values, and it covers purpose, scope and the single parameter's allowed values. The only omission is practical guidance about when in a workflow to invoke it, which is minor for a one-parameter read-only diagnostic.

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 0% and the schema has no enum, so the description carries the burden by naming the two legal values ('markdown' or 'json'). That is real added meaning beyond the schema, though it omits any note about the default or output size differences.

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 ('Run a comprehensive health check on the Engram memory system') and enumerates the problem classes it detects (fragmentation, stale knowledge, conflicting decisions, identity issues). None of the sibling tools are diagnostic, and it explicitly distinguishes itself from the CLI conflicts view, so an agent can place it without ambiguity.

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

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

The purpose plus the explicit routing note ('this is MCP doctor; for the CLI conflict view use engram conflicts list') gives clear context for when to select it and what the adjacent alternative is. It stops short of stating triggering conditions such as running it after a session or when recall results look inconsistent.

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, closed-world), so the description's job is added context — and it delivers: it discloses the on-disk path, the entry format (timestamp + lesson/decision tally), and the ~600-char truncation of summaries, which tells the agent the content is lossy. It does not say what is returned when no entry exists for the requested date, which is the one behavioral 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?

Content-wise it is front-loaded and every claim is relevant, but the entire description is duplicated in Chinese and English, roughly doubling length for the same information. Efficient in ordering, wasteful in volume.

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

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

For a two-parameter read tool with an output schema (so return shape needs no explanation), the definition covers purpose, data source, entry format, and both parameters. The remaining gaps — empty/missing-log behavior and project_folder path resolution — are minor but real.

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 0%, so the description must carry the payload — and it documents both args: project_folder as a project folder path and date as ISO YYYY-MM-DD with a documented default of today. It stops short of specifying path form (absolute vs. relative) or invalid-date behavior.

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 ('Read a project's daily log / human-readable session timeline') and immediately explains the provenance: entries appended by wrap_up_session at a known path. It explicitly distinguishes itself from search_knowledge, so an agent can choose 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?

Gives an explicit trigger ('when a new session needs a glance-able "what happened today" timeline') and names the alternative with a comparison ('faster than search_knowledge for recall'). The routing decision is fully specified.

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: it discloses that the tool writes to exports/identity_card.md and that non-owner callers are refused when governance is enabled, which explains why readOnlyHint is false despite the benign framing. What it doesn't cover is what happens on an export collision — overwrite, versioning, or error — for a tool that writes to a fixed path.

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 information architecture is strong — purpose, owner/export surface, when to use, when not to — with the operational constraint front-loaded. The only cost is that every sentence is duplicated in Chinese and English, roughly doubling the length for an English-reading agent.

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?

An output schema exists, so return-value detail is unnecessary, and with no parameters the surface is small. The description still covers purpose, the file side effect, the authorization constraint, and the sibling alternative — 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?

The tool takes zero parameters, so there is nothing to disambiguate and no schema coverage gap; baseline 4 applies. The description correctly implies the call is fully determined by the caller's identity at runtime rather than by arguments.

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 (export) and resource (the user's portable AI identity card), plus the output format (Markdown). It also enumerates the content of the card — identity, work style, quality standards, lessons — which separates it from get_user_context without the agent needing to open 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 an explicit trigger ('when another AI tool needs a self-contained summary') and an explicit exclusion with the named alternative ('if the current session only needs runtime context, use get_user_context'). The routing decision is fully determined by the text.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. Beyond that, the description discloses the error contract (version miss returns version_not_found, never approximate) and the payload-size tradeoff of include_bodies=false returning metadata only. It does not describe ordering of snapshots or pagination, so it is 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?

Content is front-loaded with purpose, then lifecycle, then purpose-in-practice, then args — a clean structure. The cost is that every sentence is duplicated in Chinese and English, roughly doubling length without adding information, which is the only thing keeping 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?

An output schema exists, so return values need not be explained. All three parameters are given meaning, the version-miss error path is named, and the HEAD-id-vs-snapshot-id trap is called out — everything an agent needs to invoke this correctly is present.

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 0%, so the description carries the full burden and does: item_id is explicitly 'the stable HEAD id, not a snapshot id' — a distinction the schema cannot convey and an easy mistake to make. It also documents include_bodies' default effect (metadata only) and version's exact-match semantics with the version_not_found failure mode instead of a nearest match.

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 revision history (superseded snapshots) of one knowledge item', and enumerates the item types it applies to (lesson/decision/playbook). This clearly distinguishes it from siblings like search_knowledge or get_relevant_knowledge, which retrieve current content rather than version chains.

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 'Lifecycle: retrieval' line plus three concrete triggers (verify prior behavior after a revision, audit a version chain, recover replaced content) tell the agent exactly when to call it. It does not name an alternative tool or state when NOT to use it, which is why it stops 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 safety and repeatability are covered structurally. The description adds real context beyond that: the result is scoped to a single project's history rather than a merged view. It does not say what happens when no snapshot exists for the folder (empty result vs. error), which is the one behavior an agent might need to branch on.

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 usage, then alternatives — a good ordering. The cost is full bilingual duplication of every sentence, which roughly doubles length without adding information for a single-language reader, though it does serve mixed-language agents.

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 read tool, the essentials are present: purpose, trigger conditions, sibling routing, and a meaningful scope constraint, with an output schema available to explain return values. The only gap is the empty/missing-snapshot case, which an agent would otherwise have to discover by calling.

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% for the single required parameter, so the schema itself says only 'string'. The description restates it as 'Project folder path', which confirms the parameter is a filesystem folder but gives no format, whether it is absolute or relative, or how to match an existing project name. Partial compensation for a total coverage gap.

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

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

States a specific verb and resource ('read the knowledge snapshot for a specific project') and immediately bounds scope ('containing only that project's history'), which cleanly separates it from the user-level sibling. An agent can distinguish it from get_user_context and get_relevant_knowledge 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 the triggering situations ('previous tech stack, known issues, notes, or collaboration history') and routes the agent elsewhere for the two adjacent needs: get_user_context for user-level identity and save_project_snapshot for writing. This covers both the read-alternative and the write-alternative, 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?

Beyond the annotations, the description discloses that only reviewed/current knowledge is returned, that superseded/pending/archived items are excluded, that meta.omitted reports {omitted_count, ids, sections, reason} when the budget trims, and that owner-only governance refusal happens before any search or telemetry side effect — a meaningful safety disclosure.

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

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

Content is front-loaded and every clause is substantive, but the full Chinese/English duplication roughly doubles the length of a description that is already dense. The information is useful; the delivery is bloated.

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?

Return shape, omission metadata, governance gating, and every parameter are covered, and an output schema exists to carry the response structure. An agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 0% for 7 parameters, and the Args block compensates fully: limit default 8 with max 20, token_budget default 2000, include_playbooks v4.20 default False with a 240-char preview cap and <=25% budget ceiling, and collapse_versions' compatibility semantics. This is exactly the added meaning the schema lacks.

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?

It states a concrete verb+resource ("Get a structured Recall Surface v1 payload") and enumerates the payload's components: identity slice, recent activity, relevant knowledge, governance metadata. That distinguishes it from narrow siblings like get_identity_card or get_knowledge_history, though it never names an alternative outright.

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 'Purpose' line gives an explicit trigger condition: new task, cross-tool handoff, or needing an actionable memory bundle in one shot. No explicit when-not or named alternative, but the aggregate framing implicitly routes simple lookups to the narrower sibling 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 readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral facts — that nothing is auto-injected into new sessions and that reads are on-demand only. It doesn't discuss result shape, but an output schema exists, so that omission is acceptable.

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

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

The purpose and the 'does not auto-load' caveat are front-loaded and earn their place, but every sentence is duplicated in Chinese and English, roughly doubling length without adding information. The Args block is efficiently formatted, so the waste is redundancy rather than tangential 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 annotations covering safety, an output schema covering return values, and zero required parameters, the description does nearly all the remaining work: purpose, trigger, and the non-auto-load caveat are all present. The only shortfall is the undocumented 'project_folder' parameter.

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 all three parameters; it explains 'tool' (empty = search all tools) and 'limit' (default 1 = most recent) with useful semantics. It says nothing about 'project_folder', leaving one of three parameters completely undefined — a real gap for an agent scoping a recovery query.

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

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

The description states a specific verb and resource ('Retrieve the most recent AI conversation context') and frames the scope as conversation history rather than user, project, or knowledge state, which is what separates it from get_user_context / get_project_context / get_relevant_knowledge. It never names a sibling explicitly, so the differentiation 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?

It gives a concrete trigger ('Call after context loss — tool restart, session disconnect') and adds a negative rule ('Does NOT auto-load into new sessions — only reads when you ask'), which prevents the agent from assuming the context is already present. No alternative tool is named for the cases this one doesn't cover.

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 a safe read (readOnlyHint, idempotent, non-destructive), so the bar is lower, yet the description still adds real behavior: filtering is by inferred project tech stack, and only reviewed/current lessons are returned while pending, superseded and archived are excluded. It also notes include_freshness leaves output unchanged when omitted, which prevents surprises. Return shape is left to the output schema, which is acceptable.

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

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

Front-loaded with purpose and lifecycle, then usage, then caveats, then args — a clean hierarchy. The full bilingual duplication doubles the token cost for any single-language reader, which is the main inefficiency, though the added lines are at least the highest-value ones.

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 an output schema present, return values need no explanation, and the three-parameter surface is fully documented. What remains unexplained is how the project tech stack is inferred and what happens if the folder path is unrecognized — minor given the retrieval-only, read-only nature of the 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 0%, so the description carries the full burden and mostly does: every parameter is defined with meaning and default value (project_folder as current project path, limit default 8, include_freshness default False with its effect on output). It stops short of stating path format expectations (absolute vs relative) or behavior when the path is unknown.

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 ('recommend the most relevant lessons for a project path') plus the distinguishing mechanism ('without search keywords'). The 'Purpose' paragraph further contrasts it with search_knowledge, so an agent can separate it from the sibling without reading 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 ('call mid-conversation when project-relevant past knowledge is needed') and an explicit exclusion with named alternative ('If the user provides explicit search keywords, use search_knowledge more directly'). This is the when/when-not/alternative triad at full strength.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real context beyond them: the output is wrapped in <engram-resume priority="high"> for client AI prioritization, and truncation over token_budget is signaled via an `omitted` field plus a trailing explanatory line. The one gap is that it does not describe latency/cost of the aggregate call or what happens when no project_folder is supplied beyond 'identity-only'.

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

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

Front-loaded with the key purpose and lifecycle, but the entire body is duplicated in Chinese and English, roughly doubling length without adding information; the 'v3.30 行业首家' marketing line is pure 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 six-parameter aggregate read tool with an output schema, the description supplies everything needed: trigger conditions, per-parameter semantics and defaults, output wrapping convention, and truncation signaling. Return value structure is covered by the output schema, so nothing critical 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 0%, so the description carries the full burden — and it documents all six parameters, including defaults and effects: project_folder (empty = identity-only), token_budget (default 2000 ≈ 8000 chars, truncation behavior), include_resume_pack and include_agent_context_pack (default false to preserve existing output shape), agent_role, and task_summary (used to shape/select the agent pack).

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 (returns a complete resume brief in one call) and explicitly frames it as the high-level aggregate endpoint versus the finer-grained siblings in the list (get_identity_card, get_project_context, get_daily_log, get_recent_context, get_relevant_knowledge). The enumerated contents (identity + project state + daily log + recent context + lessons/decisions + suggested docs) 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 a concrete trigger — 'session start, before the first user message when continuing prior work' — plus example user phrases ('接着上次', '继续之前'). It does not explicitly say when to prefer it over sibling tools like get_user_context or get_recent_context, which it partly subsumes, so an agent must infer the 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 cover read-only, idempotent and closed-world, but the description goes further: it discloses that no level touches the filesystem or other tools' files, that token_budget drops low-priority sections and appends a line naming what was omitted, and that user_prompt triggers playbook keyword matching. These are behavioral traits an agent could not infer from the 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?

Well front-loaded with the lifecycle trigger, then tiers, then cautions, then args; every block is scannable. The only waste is the line-by-line Chinese/English duplication, which roughly doubles the token cost without adding information for a single-language reader.

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

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

For a zero-required-parameter read tool with an output schema, nothing an agent needs is missing: trigger, tier contents, default, truncation behavior, and the downstream call for full playbook steps are all stated. The output schema can handle return-shape detail.

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% and the level enum is absent from the schema, so the description carries the full burden — and it does: all four parameters are explained, including the three concrete 'level' values with what each contains, the priority-based truncation semantics of token_budget, and the playbook-matching side effect of user_prompt.

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

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

States a concrete verb and resource ('Get tiered cold-start user context with latency control') plus a plain-language purpose ('understand who the user is, how they work, what they have learned, and their quality bar'). The tier breakdown makes the scope of this tool distinguishable from narrower siblings like get_identity_card or get_project_context.

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 ('call at the start of each new conversation'), an explicit default ('standard' covers most cold-start needs), and an explicit exclusion for 'full' ('use only when the user asks for a comprehensive memory review'). It also pre-empts a likely mistake by noting that importing other AI tools' files is not done here but via the terminal command.

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 readOnly/idempotent annotations, it discloses two non-obvious behaviors: long-unupdated running records are *projected* as stale_running without mutating the record, and the response deliberately omits summary text and local project paths. That is genuine added context rather than restatement of the annotation flags.

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 purpose is front-loaded in the first sentence, which is good, but the entire description is duplicated verbatim in Chinese and English, doubling length without adding a single new fact. The remaining sentences mix purpose, trigger condition, and response exclusions into one block without separation.

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

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

For a two-optional-parameter read tool with a rich annotation set and an output schema, the description covers trigger, inputs, staleness projection, and output omissions well. The only real hole is the empty-arguments / conflicting-arguments case, which an agent could plausibly hit given zero required parameters.

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 0%, so the description carries the burden, and it does explain the provenance of each parameter: idempotency_key is caller-known before the call, operation_id is one previously returned. However, with zero required parameters it never states what happens when both are empty or both are supplied, leaving the disambiguation and conflict behavior unaddressed.

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?

Opening sentence states a specific verb and resource ('read metadata-only stage status for a wrap_up_session operation') and names the sibling operation it belongs to, so an agent can immediately distinguish it from wrap_up_session itself. The scope is further narrowed ('metadata-only', 'no summary text or local project path') rather than left as a generic 'status' 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?

It gives an explicit triggering condition ('after a session-closeout transport timeout') and tells the caller which identifiers to supply depending on what they have on hand. It does not say when NOT to call it (e.g., while the operation is still in flight, or before ever calling wrap_up_session), so it is clear context without full 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?

Beyond annotations it discloses important non-obvious behavior: identical-content refusal, allow_similar_new limits, and the supersede protocol with version_required/version_conflict errors plus all-or-nothing atomicity. Strong disclosure; deductions only because the two undocumented params (project_folder, user_confirmed) leave some behavioral surface unexplained.

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?

Content is front-loaded and well-sectioned, but it is presented twice in Chinese and English, roughly doubling length without adding information. Effective but not tight.

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

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

A mutation tool with annotations and an output schema, so return values and safety profile are covered elsewhere; the description adds the routing contract, payload shapes, and error semantics. The undocumented project_folder/user_confirmed params are the remaining 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?

With 0% schema coverage the description must carry parameter meaning, and it documents kind, content_json's per-kind payload shapes, source_tool, items_json batch semantics, and allow_similar_new. However, project_folder and user_confirmed receive no explanation anywhere, leaving 2 of 7 params opaque.

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 ('Unified knowledge write endpoint') and explicitly names the three specialized targets it routes to (add_lesson / add_decision / add_playbook) based on kind. This lets an agent distinguish it from the sibling add_* tools without opening schemas.

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

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

Gives an explicit trigger ('call when the conversation produces knowledge worth persisting'), names the alternative ('you may also call the specialized tools directly'), and states the selection advantage (callers needn't know Engram's taxonomy). This is a full when/when-else/why rubric.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description confirms the tool mutates data and lists the fields it writes, but it does not add beyond-annotation specifics such as whether an existing snapshot is replaced vs merged, or the exact data-loss implications of the destructive write.

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

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

The purpose is front-loaded and the Args section is useful, but the entire content is duplicated in Chinese and English. That duplication inflates length without adding information, so it is only moderately concise.

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

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

For a two-parameter write tool with an output schema and rich annotations, the description supplies the purpose, both parameter meanings, the supported data fields, and the read alternative. A minor gap remains around overwrite vs merge semantics, which is relevant for a destructive write.

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

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

Schema description coverage is 0%, so the description must compensate, and it does document both required parameters: project_folder as the project folder path and data_json as a JSON string supporting title, tech_stack, known_issues, and notes. It lacks format examples or constraints, keeping it below a top score.

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

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

The description states a specific verb and resource: write/update a project's knowledge snapshot. It explicitly says this is a write operation, not a read, and names get_project_context as the read counterpart, making it easy to distinguish from 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?

It clearly identifies when to use the tool: saving or updating tech stack, known issues, notes, and related metadata. It also explicitly names when not to use it and which alternative to use instead: get_project_context for reading.

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, but the description still adds real value: 'pending' items are flagged pending_untrusted=true and should be treated as unconfirmed proposals, and superseded items are excluded by default. However, it doesn't disclose freshness-hint scoring criteria or how truncation interacts with item shape beyond a one-line note.

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 purpose, trigger, and routing before the long args block, and every args entry earns its place given 0% schema coverage. Slightly bloated by bilingual duplication and a prose 'Result groups' paragraph that overlaps with the include_superseded arg description.

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

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

Despite an output schema existing, it goes further and explains the group structure, pending_untrusted flagging, and clipping markers, which is exactly the behavioral context an agent needs. Only project_folder is unaccounted for, a minor omission in an otherwise complete definition.

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 0%, so the description carries the full semantic burden, and it does this well: scope values, filters_json keys with types and an example, freshness and superseded behavior, and max_field_chars truncation semantics are all spelled out. The one gap is project_folder, which appears in the schema but is never mentioned.

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 ('Search') and resource (lessons/decisions/playbooks) with the exact item types enumerated, so an agent can distinguish it from get_relevant_knowledge and explore_knowledge by resource scope alone rather than opening schemas.

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

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

Explicitly names the trigger ('when the user asks to find knowledge about a specific topic, or recalls a procedure') and gives concrete routing rules for other cases: project path with no query -> get_relevant_knowledge, existing ID -> explore_knowledge(mode="similar").

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the critical non-obvious behavior: no change is applied directly—everything becomes a pending proposal that the Owner approves or rejects. It also explains that approved identity stays in effect until approval, and that trust_boundaries changes also require review.

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 key behavior (pending proposal, Owner review) is front-loaded, and the structured Args/Field-specific-keys layout scans well. The bilingual duplication roughly doubles the length without adding information, which is the only waste.

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

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

For a three-parameter mutation tool with an output schema, it covers what matters: mutation semantics, approval workflow, valid field values, and the per-field JSON payload keys. 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 0%, so the description carries the full burden, and it does: the valid values of 'field' are enumerated, 'source_tool' is explained as field-level provenance with examples, and 'updates_json' is documented per-field with allowed keys and types/defaults (e.g. acceptance_threshold 1-5, playbook_auto_extract default true). This adds substantial meaning beyond the bare 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?

The first sentence gives a specific verb ('propose') plus resource ('identity change') and the immediate effect ('for local review'). The field enumeration further pins scope, and the distinction from read-only siblings like get_identity_card is implicit but obvious because this tool is explicitly a proposal workflow.

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 exactly when to call ('Call when changing profile, preferences, trust_boundaries, work_style, or quality_standards') and clarifies that all modes produce only pending proposals requiring Owner approval in engram review. It does not name alternatives (e.g. get_identity_card to inspect current values), so it falls short of the 5 bar for explicit alternatives/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?

Adds substantial behavior beyond the annotations: the summary feeds automatic lessons/decisions extraction, playbook drafts land in staging only when 3+ ordered steps are detected, returns a playbook_draft with confidence the agent should act on, and can be disabled via update_preferences. It does not disclose the destructive/overwrite implications that destructiveHint=true and idempotentHint=false imply, nor what happens to an existing snapshot, which is the main remaining 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?

Well front-loaded and organized into purpose, playbook behavior, alternatives, then args — but every section is duplicated in Chinese and English, roughly doubling length and diluting signal. The prose itself has no filler; the bilingual mirroring is the cost.

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?

Handles a 10-param mutation tool well: lifecycle, side effects, alternatives, and per-parameter meaning are all present, and the output schema excuses it from explaining return values. The omissions are the undisclosed user_confirmed flag and the destructiveness of snapshot updates.

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 0% schema description coverage the description carries the full load, and it does so for 9 of 10 params, including the high-value warnings that run_reconcile imports nothing and reconcile_scope is echo-only, plus idempotency retry semantics. It leaves user_confirmed entirely undocumented, which matters for a tool annotated destructive.

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 compound resource: wrap up a session by extracting knowledge, detecting playbooks, and saving a project snapshot. It explicitly contrasts itself with extract_session_insights and save_project_snapshot, so an agent can distinguish the composite tool from its narrower siblings without opening a schema.

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

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

Gives an explicit trigger ('Lifecycle: session-end — call at conversation end') plus explicit exclusions with named alternatives for the two partial-use cases (extraction only, snapshot only). Nothing about when to select this tool 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.