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

With no annotations provided, the description carries full burden. It discloses that old decisions are automatically superseded when the same question gets a different choice, and allows explicit supersedes. It also mentions lifecycle: writeback. However, it does not discuss any side effects, authorization, or persistence, though these may be 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?

The description is well-structured with headers and bullet points, but it is somewhat verbose, repeating lifecycle information and using two languages. Every sentence adds value, but it could be slightly more concise without losing clarity.

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

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

Given 12 parameters (2 required), no enums, no nested objects, and an output schema exists, the description thoroughly explains each parameter, the decision thread, and usage context. It is complete and leaves no significant gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a thorough 'Args' section documenting all 12 parameters with clear explanations in both Chinese and English, including defaults and optionality.

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 the tool records a key decision when the user explicitly chooses an option, with examples like 'we decided to use X'. It distinguishes the tool from extract_session_insights and explains the decision thread behavior, providing a specific verb ('record') and resource ('key decision').

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 explicitly says when to call: when the user explicitly makes a decision. It also provides a clear exclusion: if the user gives a session summary for automatic extraction, use extract_session_insights instead.

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

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

With no annotations, the description carries the full behavioral burden and mostly meets it: it labels the lifecycle as writeback, implies persistence through 'Record', and discloses the duplicate gate plus the allow_similar_new bypass and the revision-guidance rejection behavior. It does not mention confirmation or project-folder scoping, but the core write and dedub behaviors are made explicit.

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

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

The description is front-loaded: purpose, lifecycle, trigger condition, and alternative all appear near the top. The Args block uses a compact one-line-per-parameter format, and the bilingual duplication is functional for clarity. It is long but every section earns its place; no filler is present.

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

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

For an 11-parameter tool with no annotations and no schema descriptions, the description is remarkably complete: it covers usage boundary, alternative routing, dedub behavior, and most parameter semantics. The main gaps are project_folder and user_confirmed semantics and a description of side effects beyond 'writeback', but the output schema covers return-value expectations.

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. It provides meaningful semantics for 9 of 11 parameters, with concrete examples ('python,testing', 'claude_code'), optionality/defaults, and the relationship between source_tool and source_agent. The omissions are project_folder and user_confirmed, which are present in the schema but not explained.

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

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

The description opens with a clear verb and object: 'Record one lesson learned' / '记录单条经验教训', and immediately states the precondition 'when you already know what to save'. It also names the sibling alternative extract_session_insights, making the distinction visible without inspecting other tools.

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

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

It explicitly says when to call: 'when reusable experience is learned during conversation' and 'when the user explicitly states a lesson, pitfall, or technical finding'. It also gives an explicit exclusion: if the user provides a session summary for automatic extraction, use extract_session_insights instead.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that each playbook is stored as an individual file, is retrievable via trigger keywords, and that similar-title handling includes a bypass flag and deduplication guidance. It does not mention permissions, overwriting behavior, or other side effects, but the core write behavior and uniqueness constraints are clearly described.

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

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

The description is well-structured: purpose first, storage model second, then parameter explanations. It is bilingual, which adds length and some redundancy, but each section carries meaningful content and the core 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?

For an 18-parameter write tool with no annotations and no schema descriptions, the description covers the main usage, storage model, and deduplication behavior well. However, six schema parameters are left unexplained, including non-obvious ones like scope_type and user_confirmed, which could lead an agent to make incorrect calls or omit important context. The presence of an output schema reduces concern about return-value documentation.

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 schema has 0% description coverage across 18 parameters, so the description must compensate. It does so for 12 parameters, adding valuable semantics such as the steps_json element structure (order/action/detail), required_tools_json's no-local-paths rule, and allow_similar_new's nuanced bypass condition. Six parameters (run_id, scope_type, source_agent, project_folder, user_confirmed, last_validated_at) remain undocumented, though some are partially inferable from their names.

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: 'Record an operational playbook — a structured multi-step procedure.' It also gives concrete use cases (publishing to a registry, app deployment) and describes the storage/retrieval model, which helps distinguish it from generic memory or lesson tools. It does not explicitly name sibling alternatives, 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 clearly says when to use the tool: after completing a multi-step operational process, to preserve steps and experience for future reuse. It does not, however, state when not to use it or explicitly compare it with sibling tools like memory_store, add_lesson, or add_decision.

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?

No annotations provided. Description discloses types of issues detected (fragmentation, stale knowledge, etc.) but does not explicitly state read-only nature or other behavioral traits like side effects or auth requirements.

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

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

Bilingual structure is clear: purpose, detection list, alternative mention. Slightly redundant between languages but front-loaded and efficient overall.

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

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

Given simple tool (one param, no required, has output schema), description covers purpose and parameter. Could add example or mention non-destructiveness, but adequate for context.

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

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

Only parameter 'output_format' with default 'markdown'. Description lists allowed values ('markdown' or 'json'), which the schema (only title, type, default) lacks. Adds meaningful semantic choice.

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?

Clearly states verb 'check' (implied) and resource 'Engram memory system health'. Lists specific issues detected. Distinguishes from sibling CLI command via explicit alternative.

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?

Describes when to use (health check, detect issues) and provides alternative for CLI conflict view. Lacks explicit exclusion of other sibling tools but context implies diagnostic vs retrieval.

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?

No annotations are present, so the description carries the full burden. It discloses that the tool reads a file, specifies the exact file path, and describes the content structure (timestamped entry with lesson/decision counts and summary). It implicitly assures read-only behavior, though an explicit statement about lack of side effects would push it to 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?

The description is structured with a purpose statement, background, usage guidance, and parameter list. It is front-loaded and each sentence serves a purpose. The bilingual duplication is slightly redundant but acceptable; overall it's efficient.

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 simple two-parameter schema and the presence of an output schema (not shown), the description covers all needed aspects: what the tool does, how it works, when to use it, and what the file contains. It complements the sibling 'wrap_up_session' well. No gaps identified.

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%, but the description provides clear meanings for both parameters: project_folder (folder path) and date (ISO format, optional, defaults to today). This adds value beyond the bare schema. A minor improvement would be to include an example or constraints, but it's already sufficient.

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 the verb 'read', the resource 'project daily log', and distinguishes it from sibling 'search_knowledge' by noting it provides a faster, glance-able timeline. The bilingual text reinforces the purpose.

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 ('when a new session needs a quick overview'), provides a comparison to an alternative ('faster than search_knowledge'), and explains the file location and content format, leaving no ambiguity about appropriate use.

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 file writing (exports/identity_card.md) and authorization (refused for non-owners when governance enabled). No annotations provided, so description carries full burden; it does well but could mention side effects or idempotency.

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 in English and Chinese, plus a note. Front-loaded with action and purpose, no wasted words.

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

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

Describes what is exported (identity, work style, quality standards, lessons), conditions, and alternative. Output schema exists for return format. Complete for a simple 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?

No parameters exist, schema coverage is 100%. Description correctly omits parameter details; baseline 4 for zero-parameter tools.

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 it exports a portable AI identity card as Markdown, specifies the file path, and distinguishes from get_user_context for runtime context. The verb 'Export' and resource 'portable AI identity card' are specific and unique among 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?

Explicitly tells when to use (when another AI tool needs a self-contained summary) and when not (for runtime context, use get_user_context). Provides clear alternatives and conditions.

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 no annotations, the description carries the full burden and does so well. It discloses the retrieval lifecycle, the default metadata-only behavior when include_bodies is false, exact-version semantics, and the error behavior for missing versions. This gives the agent a clear picture of what calling the tool will and will not do.

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 bilingual structure doubles the length, but it is organized with clear labels (Lifecycle, Purpose, Args) and front-loaded with the core definition. A slightly leaner single-language version would be more concise, but the structure is easy to scan and every section earns its place.

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

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

Given the tool's moderate complexity and the absence of annotations, the description covers the essential context: lifecycle, intended use cases, parameter semantics, defaults, and edge-case behavior. An output schema exists, so explicit return-value documentation is not necessary here. Nothing critical is missing for correct invocation.

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%, but the Args section fully compensates. It explains that item_id is the stable HEAD id not a snapshot id, that include_bodies defaults to false and controls body inclusion, and that version is an exact optional lookup with defined miss behavior. This is exactly the semantic depth the bare 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?

The description clearly states the tool returns the revision history of one knowledge item with a specific verb ('Return the revision history') and resource ('one knowledge item'). It distinguishes itself from sibling tools like search_knowledge and get_relevant_knowledge by focusing on historical snapshots rather than current content.

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 guidance: 'call when you need what changed on an item, when, and what the prior body looked like', plus concrete use cases (audit, recover replaced content). It also gives a when-not nuance: a version miss returns version_not_found, never a nearest match, which prevents misuse.

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 no annotations, the description carries full burden. It clearly states the tool is read-only ('读取', 'Read'), and specifies the scope ('只含该项目的历史'), implying no side effects. Missing details like authentication or rate limits, but these are minor for a read operation. The description is transparent enough for safe selection.

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

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

The description is well-structured with bilingual sections and clear headings (用途/目的, 注意/Note). It is concise (~100 words) and front-loads the purpose. A small improvement could be removing redundant phrasing, but overall it is efficient and easy to scan.

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 tool has only one parameter, no annotations, but an output schema exists, the description adequately covers purpose, usage guidelines, parameter semantics (minimally), and behavioral traits. It mentions what the tool contains (history of that project) but does not describe return structure, which output schema likely provides. It is sufficiently complete for agent selection.

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. The description only says '项目文件夹路径。 / Project folder path.' which adds minimal meaning beyond the schema's type string. It does not clarify expected format (absolute/relative), or provide examples. This is insufficient for a parameter-rich tool.

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 explicitly states the tool reads a knowledge snapshot for a specific project and contains only that project's history, using specific verbs and resource. It also distinguishes from siblings like get_user_context and save_project_snapshot, clarifying its scope.

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 clear when-to-use guidance: '想了解某个项目之前的技术栈、已知问题、协作次数时调用' (Call when you need a project's previous tech stack, known issues, notes, or collaboration history). It also explicitly mentions two alternatives: get_user_context for user-level context and save_project_snapshot for writing, making the usage context unambiguous.

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 no annotations provided, the description carries the full burden, and it delivers substantial behavioral detail. It discloses owner-only access when governance is enabled, explains that non-owners are refused before any search or telemetry side effect occurs, and details playbook pointer bucket constraints including max items and budget share.

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

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

The description is well structured and front-loaded: purpose, usage, behavioral notes, then args. The bilingual duplication makes it longer than strictly necessary, but every substantive point earns its place given the absence of schema descriptions and annotations.

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

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

The description is complete for a 7-parameter tool with no annotations: it covers purpose, invocation context, access control, side-effect behavior, and each parameter. Since an output schema exists, the return value does not need explanation, and nothing critical appears missing for correct invocation.

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 input schema has zero description coverage for all seven parameters, and the description fully compensates by documenting each argument with defaults, types, constraints, and behavior. It even adds important detail such as limit max 20, token_budget default 2000, and the precise playbook inclusion rules for include_playbooks.

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 identifies the tool as returning a structured Recall Surface v1 payload: a memory bundle containing identity, recent activity, relevant knowledge, and governance metadata. It positions the tool as an aggregate view, which distinguishes it from narrower siblings like get_identity_card, get_relevant_knowledge, and get_recent_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?

The description explicitly states when to call it: on new tasks, cross-tool handoffs, or when a single executable memory bundle is needed. It gives clear context but does not explicitly name alternatives or state when not to use it, so it misses the full when-not/alternative guidance required for 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?

With no annotations, the description carries the burden. It discloses that the tool only reads data and does not auto-load into new sessions, which is key behavioral information. It does not mention side effects, but as a read operation, that is sufficient.

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

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

The description is structured with purpose and usage sections and is reasonably concise. The bilingual text adds length but each sentence provides value. It could be slightly more compact by dropping repetition.

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 having an output schema, the description does not explain the return format. It misses documenting the 'project_folder' parameter. For a tool that recovers context, the description covers the main use case but lacks completeness on parameters and return.

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

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

The description adds meaning for the 'tool' and 'limit' parameters (with defaults and purpose), but the 'project_folder' parameter in the input schema is completely undocumented. Given 0% schema description coverage, the description partially compensates but misses one parameter.

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 the verb 'retrieve' and resource 'most recent conversation context', and specifies the scenario of context loss after tool restart or session disconnect. It distinguishes purpose from sibling tools like get_recall or get_user_context by focusing on recent context recovery.

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 explicitly tells when to use the tool (after context loss) and clarifies it does not auto-load. However, it does not mention when not to use it or reference specific sibling 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool follows lifecycle 'retrieval', filters by tech stack, and includes a parameter include_freshness that attaches a freshness hint. It does not mention side effects, but as a retrieval tool this is acceptable. The response format is covered by the output schema.

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

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

The description is clear and well-structured, using bilingual text and bullet points for parameters. While it could be slightly more concise by removing redundant phrasing, it remains efficient and front-loads key 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?

Given the tool has 3 parameters, an output schema, and no nested objects, the description provides sufficient context: purpose, usage, lifecycle, and parameter details. It could mention handling of invalid project paths, but that is not critical for selection and invocation.

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. It explains all three parameters: project_folder (current project path), limit (max items, default 8), and include_freshness (attach freshness hint, default false). This adds meaning beyond the schema's type and default values.

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 the tool's purpose: automatically recommend relevant lessons for a project path without search keywords. It provides both Chinese and English explanations and distinguishes from the sibling tool search_knowledge by noting it's for when the project path is known but search terms are not.

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 explicitly provides usage guidelines: call when you know the project path but not search terms, and if the user provides explicit keywords, use search_knowledge instead. This helps the agent decide when to invoke this tool vs 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?

With no annotations provided, the description carries the full burden. It discloses the output format (wrapped in <engram-resume priority='high'>), lifecycle (session start), and optional structured packs. It could be more explicit about read-only nature and potential side effects, but overall provides good behavioral context.

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

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

The description is well-structured with sections for purpose, lifecycle, and arguments. Key information is front-loaded. It is slightly long but each section serves a purpose. Minor redundancies in bilingual text could be trimmed.

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 tool's complexity (6 params, output schema exists), the description covers the main use cases, parameter details, lifecycle, and output format. It lacks mention of error handling or behavior for invalid project_folder, but overall provides sufficient context for correct invocation.

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% with no descriptions in the schema. The description fully explains each of the 6 parameters, including defaults, behavior (e.g., token_budget as soft cap), and the effect of include_resume_pack and include_agent_context_pack. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states it returns a cross-session, cross-tool resume brief including identity, project state, daily log, recent context, lessons/decisions, and suggested docs. This specific verb-resource combination distinguishes it from sibling tools like get_recent_context or get_daily_log.

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 provides explicit usage context: call at session start, before first user message, or when user indicates continuing prior work. It gives example user phrases. However, it lacks explicit when-not-to-use or alternatives for different scenarios.

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 no annotations, the description fully discloses behavior: quick tier is pure JSON reads (low latency), standard adds quality/domains/lessons, full includes conflict detection and auto-sync side effects. It also notes that standard skips expensive reconciliation.

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

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

The description is well-structured with bilingual text, bullet points, and clear sections. It is slightly lengthy but every sentence adds value; could trim some repetition but overall effective.

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 four parameters, no annotations, and the presence of an output schema, the description covers all necessary aspects: purpose, usage context, parameter details, tier behavior, and side effects. It is complete for an AI agent to correctly select and invoke the tool.

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

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

Schema coverage is 0%, but the description explains all four parameters in detail: project_folder (optional), level (tiers and defaults), token_budget (priority-based clipping), and user_prompt (playbook matching). This adds significant 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 description clearly states the tool retrieves user context at conversation start, with three tiers (quick/standard/full) each detailed. It distinguishes from sibling tools like get_identity_card or get_project_context by specifying it provides comprehensive context including preferences, quality, lessons, etc.

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 explicitly says to call at the start of each conversation and notes the standard tier suffices for most cases, with full tier reserved for explicit user requests. However, it does not directly compare with sibling tools or state when to use them instead.

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

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

With no annotations provided, the description carries the full behavioral burden and meets it well. It discloses that the operation is metadata-only, read-only, that long-unupdated running records are projected as stale_running without mutating the record, and that no summary text or local path is returned. These are meaningful side-effect guarantees beyond a generic 'get'.

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 bilingual format doubles the length, but each language block is compact and purposeful, with key facts front-loaded: metadata-only, read-only, stale_running, and non-return of summary/path. There is no filler; the repetition is acceptable for multilingual tooling.

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 absence of annotations and a bare schema, the description delivers a complete operational picture: when to use it, which inputs are valid, what behavior to expect around stale states, and what is deliberately excluded. An output schema exists to define return fields, so nothing essential is missing for an agent to select and invoke this 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 0%, so the description must compensate, and it does. It explains both parameters' roles: idempotency_key is caller-known and operation_id was returned by a prior call, and either can be used to query. It does not specify precedence or validation when both are supplied, but it provides enough context for correct invocation.

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

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

Description uses a specific verb ('读取/read metadata-only stage status') tied to a concrete resource (wrap_up_session), and clearly distinguishes itself from the mutation-oriented sibling wrap_up_session by stating it is read-only and metadata-only. It also states what it does not return (summary text or local project path), which further disambiguates it from retrieval tools like get_resume_brief.

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 explicitly names the triggering scenario: after a session-closeout transport timeout, using a caller-known idempotency_key or a returned operation_id. It also includes a clear when-not by excluding summary text and local path retrieval, so an agent knows this tool is for status checking, not content retrieval.

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 no annotations, the description carries the full burden and does dislose routing behavior, batch semantics ('playbook not supported in batch'), per-kind content formats, and the writeback lifecycle. However, it says nothing about the likely write-gating behaviors implied by the undocumented booleans — user_confirmed (confirmation?) and allow_similar_new (duplicate similarity check?) — nor what happens to existing knowledge on overwrite. For a write tool, these are material behavioral facts.

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 bilingual text doubles length, but each block earns its place: purpose line, lifecycle line, routing guidance, then a well-structured Args section with high-value per-kind format examples. The only real inefficiency is the intentional bilingual duplication; otherwise 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?

Complexity is high — 7 params, single/batch dual modes, and 3 kinds with different content shapes — and the description handles routing, mode selection, and formats well, while the presence of an output schema relieves it of return-value duty. The three unaddressed params and the absence of explicit guidance on when to choose batch vs single mode (only the trigger 'items_json provided' is stated) leave real gaps for correct invocation.

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 richly for 4 of 7 params: kind's allowed values, content_json's per-kind JSON schemas (lesson / decision / playbook examples), items_json's batch trigger and playbook restriction, and source_tool examples. But project_folder, user_confirmed, and allow_similar_new appear in neither the schema nor the description, leaving critical control knobs completely 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 and resource with precision: 'Unified knowledge write endpoint — routes to add_lesson / add_decision / add_playbook based on kind.' The routing behavior differentiates it from the specialized add_* siblings and scopes the tool's exact job in the first line.

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 ties invocation to lifecycle: 'writeback — call when the conversation produces knowledge worth persisting.' It also names the alternates and the selection condition: call add_lesson / add_decision / add_playbook directly when the kind is already known, and use this unified entry when the caller wants to avoid Engram's internal taxonomy.

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?

Describes as a write operation but lacks details on side effects, permissions, or update vs. overwrite behavior. With no annotations, more transparency would be beneficial.

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?

Bilingual but each sentence adds value; no fluff, but slightly redundant in both languages. Efficient overall.

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

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

Covers purpose, usage, and parameters. With output schema present, return value not needed. Lacks potential error handling or prerequisites, but adequate for a simple write 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 has 0% description coverage, but description adds meaning for both parameters: project_folder path and data_json fields (title, tech_stack, known_issues, notes).

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?

Clearly states it writes or updates a project snapshot, distinguishes from read operation 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?

Explicitly says when to use (save/update) and when not (use get_project_context for reading), providing clear direction.

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?

No annotations are provided, so the description bears full responsibility. It discloses the lifecycle as retrieval (read-only), explains parameter effects (e.g., truncation with max_field_chars, freshness hints), and implies non-destructive behavior. It does not explicitly state auth or rate limits, but for a search tool the transparency is good.

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

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

The description is front-loaded with a summary and lifecycle, then usage guidance, then parameter details. It is well-structured but somewhat verbose due to bilingual text. Every sentence is useful, but conciseness could be slightly improved.

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 tool's complexity (7 parameters, no annotations, output schema exists), the description covers key behaviors: parameter explanations, truncation, freshness hints. It lacks error handling details but is sufficient for an AI agent to use 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 explain parameters. It does so for most (query, scope, limit, filters_json with example, include_freshness, max_field_chars) but omits project_folder, leaving a gap. The explanations add value beyond the schema (e.g., filters_json keys).

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 the tool searches a knowledge base of lessons, decisions, and playbooks by keyword. It distinguishes from siblings like get_relevant_knowledge (for project path without query) and explore_knowledge (for existing ID), making the purpose 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?

The description explicitly says when to call this tool (when user asks to find knowledge or recalls a procedure) and when not to, providing alternative tools (get_relevant_knowledge, explore_knowledge). This gives clear usage guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool updates identity fields, details field-specific keys, and mentions source_tool for provenance. It does not discuss idempotency, auth, or side effects, but the mutation behavior is evident. The level of detail compensates for the lack of annotations.

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

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

The description is front-loaded with purpose and structured into clear sections. However, bilingual text (Chinese and English) doubles the length. Every sentence adds value, but it could be more concise if it used only one language.

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 three parameters and no annotations, the description covers the input thoroughly. An output schema exists (according to context signals), so the description need not explain return values. It adequately addresses the complexities of field management.

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%, but the description thoroughly explains each parameter: field lists valid values, updates_json is described as a JSON string, and source_tool is for provenance. Additionally, it provides exhaustive field-specific keys for each valid field value, which adds immense 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?

The description clearly states that the tool updates one identity field, listing the specific fields (profile, preferences, trust_boundaries, work_style, quality_standards) and their sub-keys. It distinguishes the tool from siblings like add_decision, add_lesson, etc., which have different purposes.

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 explicitly states when to call: 'Call when changing profile, preferences, trust_boundaries, work_style, or quality_standards.' It also provides a note about valid keys and managing sensitive-field boundaries. Missing explicit when-not-to-use or alternatives, but the 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?

No annotations are present, so the description carries the full burden. It discloses the automatic Playbook side effect, writes to staging, the configuration toggle via `update_preferences`, idempotency/retry behavior, and reconcile scoping. It even instructs AI tools on how to handle the returned `confidence` field. This is thorough behavioral 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?

The bilingual description is long but front-loaded with a clear purpose and sibling differentiation, then organized into behavior and Args sections. The Lifecycle sentence partly repeats the Purpose sentence, and dual-language blocks double length, but every paragraph still contributes useful content and the structure is easy to scan.

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?

It covers lifecycle, sibling differentiation, auto-extraction side effects, optional snapshot behavior, config toggle, and idempotency. An output schema exists, so not detailing return values is fine. The main omission is the undocumented `run_reconcile` and `user_confirmed` parameters, which prevents the description from being fully complete for a complex write operation.

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. It gives rich semantics for 8 of 10 parameters, including idempotency retry behavior and `reconcile_scope` values. However, `run_reconcile` and `user_confirmed` are never mentioned, leaving ambiguity about their purpose and effect, which is a significant gap for a 10-parameter tool.

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

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

The description opens with a clear verb-resource-scope sentence: 'Wrap up a session in one step: extract knowledge, detect playbooks, and save a project snapshot.' It also distinguishes itself from siblings by separately naming `extract_session_insights` and `save_project_snapshot`, making the combined nature of this tool obvious.

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 explicitly states the lifecycle ('call at conversation end') and provides direct when/when-not guidance: use `extract_session_insights` when you only want extraction, and `save_project_snapshot` when you only want a snapshot. This is explicit sibling routing with no inference required.

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