memkin

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

With no annotations provided, the description discloses the return shape ('ok plus slug/date/summary') and error handling. It implies mutation via 'append,' but lacks details on permissions or idempotency. Still, it provides key 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?

Very concise at 6 lines, structured with markdown headers. Every sentence adds value: action, usage, return, error. Front-loaded with the core purpose.

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

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

Given 6 parameters, 3 required, an output schema, and no annotations, the description covers purpose, usage, error, and return. It omits details on optional parameters (detail, source, provenance) but the schema covers them. Adequate for an 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 coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what the schema provides for parameters. It only references three required parameters in the return hint, without deeper explanation.

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 'Append a dated memory event to an existing page,' using a specific verb and resource. It distinguishes itself from the sibling tool `put_page` by specifying when not to use it ('full page replacement; use put_page').

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 provides when-to-use ('record project progress, decisions, or notable events') and when-not-to-use ('full page replacement; use put_page'). Includes error recovery guidance ('fix invalid date or find the correct page slug').

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, so description carries full burden. It discloses the fixed 7-section structure, return type (SynthesisResult with sections, answer, citations, gaps), and error behavior (valid ISO date required). No contradictions with missing 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?

Concise, well-structured with explicit sections (title, description, when to use/not, returns, error). Every sentence adds essential information without redundancy. Front-loaded with core purpose.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, return structure, and error handling. No gaps given the tool's complexity.

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

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

Schema coverage is 100% for the single parameter 'date', but description adds value by specifying format (YYYY-MM-DD), default (today local time), and error condition. Baseline 3 plus extra context yields 4.

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 states 'Generate a synthesized cross-channel daily report in 7 fixed sections' – a clear verb+resource+scope. It explicitly distinguishes from siblings by naming 'recall' and 'query' as alternatives for arbitrary recall, making purpose unmistakable.

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

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

Explicit when-to-use ('help me write today's daily report') with a list of aggregated signals, and a clear when-NOT-to-use ('arbitrary recall; use recall/query'). Provides context for tool selection.

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, so the description must cover behavioral traits. It mentions bounded depth, return structure (focus node, graph nodes, edges), and error handling (search for correct slug). While it doesn't discuss auth or rate limits, it provides sufficient context for a read-only graph exploration.

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?

Description is concise and well-structured with sections (When to use, When NOT to use, Returns, On error). Every sentence adds value; there is no redundancy.

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

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

Given the tool's complexity (graph traversal with depth/direction), the description explains what it returns, how to handle errors, and provides usage guidance. The presence of an output schema (though not detailed here) further supports completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema already provides for slug, depth, and direction. It repeats parameter names but offers no additional semantic context.

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 explores graph relationships around a page, using a specific verb and resource. It distinguishes itself from sibling tools like get_page_context by explicitly noting when not to use it.

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

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

Provides explicit 'When to use' and 'When NOT to use' guidance, including a specific alternative (get_page_context). This helps agents decide between this tool and its siblings.

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. It states the return type ('entity page with all linked signals and timeline') but lacks details on side effects, permissions, or limitations. Adequate but not rich.

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

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

Three concise sentences plus a header, front-loaded with 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?

For a simple tool with one parameter and no output schema, the description covers the core behavior. It could mention time range or ordering, but overall it is reasonably complete for decision-making.

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

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

Schema coverage is 100% with a single parameter well-described in the schema. The description does not add extra meaning beyond what the schema provides (e.g., format or constraints), so baseline 3 applies.

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

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

The verb 'get' and resource 'entity profile' are clear. The description states it returns a comprehensive view with signals and timeline, distinguishing it from siblings like list_signals_by_entity (only signals) and timeline_feed (only timeline).

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 includes a 'When to use' clause specifying need for a comprehensive view of a person, project, or tool. However, it does not mention when not to use or list 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, the description fully carries the burden. It discloses return fields (status, page/chunk counts, MCP version, legacy setting) and error handling (inspect server logs). However, it does not explicitly state that the tool is read-only or has no side effects.

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 extremely concise with no wasted words. It uses clear structure with headings and bullet-like sections. Every sentence adds value, e.g., 'On error: inspect server logs.'

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 zero parameters and the presence of an output schema, the description is complete. It covers purpose, usage, return values, and error handling. No additional information is needed for this simple health-check 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?

The input schema has zero parameters, and schema description coverage is 100% (empty). The description does not need to add parameter meaning. Baseline for 0 parameters is 4, which is appropriate.

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

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

The description explicitly states 'Return Memkin MCP health and capability metadata.', which is a specific verb and resource. It clearly distinguishes from sibling tools like 'get_entity_profile' or 'get_session_context' by focusing on health diagnostics.

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 guidelines: 'When to use: diagnose database counts, MCP version, and legacy tool exposure.' and 'When NOT to use: retrieve memory content; use read tools.' This clearly directs the agent to appropriate 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 provided, so description carries full burden. It discloses return values (page, tags, limited related context, provenance) and error handling (if slug missing, search for correct slug first). However, it does not explicitly state the tool is read-only or mention any side effects. This is a minor gap, hence 4.

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?

Highly concise and well-structured with headings, bullet points, and clear separation of sections. Each sentence is informative without redundancy.

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

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

Given the presence of an output schema and the tool's moderate complexity, the description covers usage, error handling, parameter context, and return values adequately. It also differentiates from siblings, making it complete for agent decision-making.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds minimal extra meaning beyond the schema; it mentions 'limit' implicitly via 'maximum related items' but the schema already says that. Baseline 3 is appropriate.

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

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

The description clearly states the purpose: 'Read a page plus nearby memory context.' It uses a specific verb ('Read') and resource ('page'), and distinguishes from siblings like `put_page` (write) and `query`/`search` (broad recall).

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

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

Explicit when-to-use: 'after finding a slug and needing page, tags, links, backlinks, timeline, or chunks in one call.' Also when-not-to-use: 'broad recall without a slug; use `query` or `search` first.' Clearly guides agent 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 mentions returning a recent activity summary but omits details like side effects (likely none), data scope, or performance. Adequate but not comprehensive.

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

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

Extremely concise with clear structure: heading, purpose, usage, return. Every sentence is informative.

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?

Tool has one optional parameter and no output schema. Description covers purpose and basic return type but lacks detail on the summary structure. Adequate for a simple tool but could be improved.

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 describes the only parameter 'days' fully. Description adds no new meaning beyond 'given day window'. Baseline of 3 is appropriate.

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

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

The description clearly states the tool loads working memory for session bootstrap, with a specific verb and resource. It distinguishes itself from siblings as a session-wide context loader.

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: at the start of every session. Does not cover when not to use, but context makes it 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 provided, so the description carries full burden. It mentions the return value ('ok plus current handles') but does not disclose behavioral traits like idempotency, effects of duplicate aliases, or required permissions. The mutation nature is implied but not detailed.

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 extremely concise: four short sentences including the title. It uses markdown headers for structure. Every sentence provides necessary information without redundancy.

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

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

The tool has 4 parameters and no output schema. The description covers purpose, usage, and return value. However, it omits details about the 'strength' parameter and potential error conditions. Given its moderate complexity, the description is adequate but not fully comprehensive.

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

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

Schema description coverage is 100% (all four parameters have descriptions in the schema). The tool description adds minimal extra meaning beyond listing examples ('email, feishu_open_id, nickname'). Baseline 3 is appropriate as schema already documents parameters.

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 action: 'Add an alias handle to a canonical person page.' The verb 'Add' and resource 'alias handle to a canonical person page' are specific. It distinguishes from sibling tools like remove_person_alias and list_person_handles.

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 context: 'When to use: link a new identifier (email, feishu_open_id, nickname) to a person.' This guides the agent on correct usage. It doesn't explicitly mention when not to use or alternatives, but the context is clear given 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?

No annotations are provided, so the description must carry behavioral information. It states the return format (array of handles with kind, value, strength), which is helpful. However, it does not clarify if the operation is read-only or disclose any side effects, authentication needs, or rate limits, which is adequate but not thorough.

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 brief, consisting of a heading, a one-sentence definition, a usage line, and a returns line. It is front-loaded and to the point, with no unnecessary information, though it could benefit from better structure (e.g., separate sections).

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 simplicity (one parameter, no nested objects, no output schema), the description covers the essential aspects: what it lists and its purpose. It does not mention pagination or optional filtering, but for a 'list all' tool this is acceptable.

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

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

Schema coverage is 100% with a clear description for the sole parameter 'canonical_slug' as 'Canonical person page slug.' The tool description does not add further meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'List all handles for a canonical person.' It uses a specific verb and resource, and distinguishes itself from sibling tools like link_person_alias or remove_person_alias which modify or delete handles.

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 context: 'When to use: check known aliases for a person.' It gives a clear use case, though it does not mention when not to use or list alternatives, which would elevate the score.

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 describes the tool as a read operation (list) but does not disclose any behavioral traits such as authentication requirements, rate limits, or side effects. The description is minimal and adequate but lacks depth.

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 extremely concise: two lines of substantive content plus a heading. Every sentence adds value: purpose, usage context, and return format. 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?

The tool has 3 parameters (1 required) and no output schema. The description explains it returns signals with type, title, and summary, which is sufficient for basic use. However, it could mention pagination behavior given the limit parameter, and it lacks details on ordering or filtering behavior. Slightly incomplete but acceptable.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds no extra meaning beyond the schema; it only mentions returned fields. Baseline of 3 is appropriate since the description does not enhance parameter understanding.

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 lists all signals anchored to an entity, with specific verb 'List' and resource 'signals anchored to an entity'. It distinguishes from siblings like search or query by specifying the scoped retrieval for a specific person/project/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?

The description includes 'When to use: retrieve decisions, tasks, knowledge, etc. for a specific person/project/tool' which gives clear context for appropriate usage. However, it does not explicitly mention when not to use or alternatives, so it lacks 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?

No annotations provided, but description discloses return format ('Returns: ok plus action/from/to') and error handling. Mutation is implied by 'Add or remove', with no contradictions.

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?

Description is very concise, uses headings and bullet points effectively, and front-loads the main action without unnecessary words.

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

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

Given 6 parameters (3 required), output schema, and nested objects, the description covers purpose, usage, return value, and error handling comprehensively, leaving minimal gaps for agent understanding.

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

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

Schema coverage is 100%, but description adds value by listing example relationship types (mentions, depends_on, works_on) beyond the schema's generic 'Relationship type', and clarifies 'context' field as 'short relationship context'.

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 'Add or remove graph links between pages', which is a specific verb+resource. It also distinguishes from sibling 'manage_tags' by explicitly stating when not to use.

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 ('maintain relationships such as mentions, depends_on, or works_on') and when-not-to-use ('tagging; use manage_tags'), plus error guidance ('search for missing page slugs before retrying').

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 must carry the full burden. It discloses that the tool mutates tags, returns 'ok plus action/slug/tags', and gives error-handling hints ('search for the page slug or provide at least one tag'). Lacks details on idempotency or concurrent usage, but adequate for its simplicity.

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?

Concise at ~6 lines with clear headings and bullet-like structure. Every sentence serves a purpose: purpose, usage guidance, return type, and error handling. No redundancy.

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

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

Given a simple tool with 3 parameters, full schema coverage, and an output schema (implied by 'Returns: ...'), the description covers all essential aspects: purpose, usage, return, and error recovery. It is complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100% (all three parameters described in schema). The description adds only marginal value ('stable tags' context) and does not enhance understanding beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description starts with 'Add or remove tags on a page' – a clear verb+resource+action. It distinguishes itself from 'manage_links' which handles graph relationships, making the tool's unique purpose immediately 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?

Explicitly states when to use ('classify memory pages with stable tags') and when NOT to use ('graph relationships; use manage_links'). Also provides error recovery guidance, leaving no ambiguity for an AI agent.

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

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

No annotations are provided, so the description carries full burden. It states that it merges and moves handles and returns 'ok plus merged handles', but does not disclose whether the source person is deleted or other potential side effects.

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 extremely concise with no wasted words: a short header, a one-sentence action, a usage hint, and a return statement, all 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?

While the description provides usage context and mentions the return value, it lacks details about side effects (e.g., deletion of source, handling of shared data) that would be important for a destructive merge 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 coverage is 100% with clear parameter descriptions ('Source person slug' and 'Target person slug'). The description adds minimal value beyond the schema, meeting the baseline.

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

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

The description clearly states the verb 'merge' and resource 'persons', and the purpose of moving all handles when two person pages represent the same individual, distinguishing it from similar tools like link_person_alias.

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 ('two person pages represent the same individual'), but does not mention alternatives or when not to use it, which would improve the score.

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 that profiling is passive and local, the four-color shell is a mapping not a clinical diagnosis, and tool returns suggestions only—never manipulation. Also notes error handling for missing page slug. No annotations exist, so description carries full burden.

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

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

Well-structured with clear sections (What it does, When to use/not use, Returns, On error). Each sentence is purposeful and concise, no wasted words.

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

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

Given two parameters, no output schema, and no annotations, the description provides thorough context: purpose, usage boundaries, return type, ethical note, and error guidance. Fully adequate for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described. Description adds extra context like 'toward a specific goal' for the optional goal parameter, which enriches understanding beyond 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?

Clearly states the tool prepares a goal-conditioned communication strategy from a passively-inferred profile. Uses specific verb 'prepare' and resource 'communication strategy'. Distinguishes from sibling `get_entity_profile` which provides raw facts.

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

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

Explicitly states 'When to use: before talking to someone' and 'When NOT to use: raw facts; use get_entity_profile/query'. Provides clear guidance on 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?

Despite no annotations, the description discloses idempotency, return fields (ok, slug, changed flag, etc.), and error advice. Missing details on authentication or rate limits, but core behaviors are covered well for a simple write tool.

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?

Concise, well-structured with short sections. Front-loaded with purpose and usage. Every sentence adds value without 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?

Given the tool's simplicity (2 params, 100% schema coverage, output schema present via described returns), the description covers purpose, usage, returns, and error handling. Could mention more about content format but schema already specifies 'Full markdown content'.

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?

Input schema has 100% coverage with clear descriptions for slug and content. Description adds error hint ('fix slug or non-empty content') but does not significantly enhance meaning beyond the schema. Baseline 3 applies.

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

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

Description clearly states 'Create or update a Memkin page idempotently', identifying the resource and action. It distinguishes from sibling tool add_timeline_entry by specifying the use case for durable pages vs. dated events.

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

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

Explicit 'When to use' and 'When NOT to use' sections provide clear guidance, including a direct alternative (add_timeline_entry). This helps the agent decide correctly.

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

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

No annotations provided, so description carries full burden. Discloses that results are ranked with fields like slug, title, type, snippet, score, provenance. Gives error recovery guidance. Could mention default limit and clamping behavior (present in schema but not description), but overall adds value.

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?

Extremely concise with structured bullets and headings. Four compact lines (excluding title) that front-load purpose and include return format and error context. No wasted words.

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

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

Given output schema exists (not shown but indicated), description adequately covers return summary and error handling. With 11 parameters, description is comprehensive enough for agent decision-making. Minor omission: default limit/clamping not restated.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema, merely referencing 'filters' generically. Meets baseline but does not exceed.

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 'Semantic search across Memkin memory,' clearly stating the verb and resource. It distinguishes from sibling 'search' by specifying fuzzy/conceptual recall versus exact keyword matching.

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 use ('fuzzy, conceptual recall') and when NOT to use ('exact keyword matching; use `search` instead'). Also provides error handling advice ('broaden filters or retry with fewer constraints').

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 the return type (SynthesisResult with answer, citations, gaps) and error handling (at least one parameter required). It implies a read-only operation but does not explicitly state safety guarantees. Still, it provides substantial 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?

Five clearly separated sections (title, description, usage, returns, error) with no redundant information. Every sentence serves a purpose, 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?

Given the tool's moderate complexity (3 parameters, no output schema), the description covers purpose, parameter constraints, output format, error behavior, and sibling differentiation. An agent can confidently use this tool without additional 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?

Schema coverage is 100%, so baseline is 3. The description adds value by stating the constraint 'provide at least one of entity, query, or time', which is not in the schema. This compensates for the lack of enum or additional constraints.

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 recalls a synthesized, cited summary for an entity, query, or time window. It uses a specific verb-resource pair and distinguishes from siblings by noting it provides composed recall with citations vs raw snippets from query/search.

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

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

Explicit 'When to use' and 'When NOT to use' sections with specific alternative tool names (query, search). This is textbook perfect guidance, leaving no ambiguity about when to invoke this tool.

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 only states the action and return ('ok plus updated handles') without disclosing side effects, permission requirements, or whether the operation is destructive. This is insufficient for a mutation tool.

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 very short and front-loaded, with no wasted words. Every sentence serves a purpose, but it lacks some details, preventing a perfect score.

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 simplicity of the tool (2 required string parameters, no output schema), the description is adequate but minimal. It does not explain whether the slug must exist, or any constraints on the rename, leaving some gaps for a complete understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond the schema's property descriptions for 'from' and 'to.' It provides no extra context or syntax details.

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 'Rename a person's canonical slug,' using a specific verb and resource. This distinguishes it from sibling tools like 'merge_persons' and 'link_person_alias,' which handle different operations.

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 guidance is given: 'When to use: correct or update a person's canonical page slug.' It does not provide alternatives or explicit when-not-to-use scenarios, but the context is clear enough for this purpose.

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, and the description does not disclose any behavioral traits beyond the minimal action. It omits details on permissions, side effects (e.g., if handle doesn't exist), or error conditions.

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

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

The description is very short and direct, with no redundant information. Every sentence serves a purpose, though it could be slightly expanded for 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 no output schema and the tool being a deletion action, the description lacks completeness. It does not explain the meaning of the return value 'ok' or provide prerequisites or error handling.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; it merely restates 'handle' without clarifying formats or constraints.

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 'Remove' and the resource 'a handle from any person', distinguishing it from sibling tools like 'link_person_alias' which adds handles.

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 provides a specific use case: 'correct a wrong alias assignment'. However, it lacks guidance on when not to use it or 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 provided, so description carries burden. Mentions return type and error handling but lacks details on auth, rate limits, or side effects.

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?

Structured with headings and bullets, front-loaded, efficient. Every sentence adds value.

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 many parameters and output schema exists, description covers purpose, guidelines, and error handling. Could mention more about result behavior but overall adequate.

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

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

Schema description coverage is 100%, so description adds no extra parameter meaning beyond schema. Baseline 3 is appropriate.

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

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

Clearly states 'Keyword search across Memkin memory' and specifies exact words, identifiers, tokens, etc. Distinguishes from sibling 'query' for fuzzy recall.

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 (exact words) and when not to (fuzzy recall, use 'query'). Also provides error handling 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 provided, but the description details return structure (answer with citations, citations[], gaps[]) and error requirements (intent registered, scope non-empty). Lacks info on auth or rate limits but sufficient for a non-destructive tool.

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?

Extremely concise: one sentence for main action, then bullet-pointed usage guidance, return, and error handling. Every sentence earns its place, front-loaded with purpose.

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

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

With no output schema, description covers return values and error states. Mentions gaps and citations. Could detail the exact shape of citations and gaps, but overall complete for a synthesis tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal value beyond schema: notes intent must be registered, and gives example 'recall'. Not significantly augmenting.

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?

Explicitly states it synthesizes a cited, gap-aware answer from memory using an intent template. Clearly differentiates from siblings like query/search which return raw snippets.

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 (composed answer) and when-not-to-use (raw snippets, use query/search). Offers concrete alternative 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?

The description discloses return fields and error handling hints ('On error: fix invalid date filters and retry'). Although no annotations are provided, the description effectively communicates the read-only nature and basic behavior.

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

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

The description is concise, well-structured with headings, and front-loads essential info. Each sentence serves a purpose without redundancy.

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

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

Given the tool's complexity (11 parameters, optional, output schema exists), the description covers purpose, usage guidelines, return format, and error handling, providing a complete picture for the agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal additional meaning beyond aligning with use cases like date-bounded and source-filtered scans.

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 'Read global timeline memories,' using a specific verb and resource. It explicitly distinguishes from the sibling tool 'get_page_context' by stating when NOT to use this 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?

The description provides explicit 'When to use' and 'When NOT to use' sections, mentioning alternatives like 'get_page_context'. This gives clear guidance on appropriate contexts.

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, so description carries full burden. It discloses pulling playbook pages along the precedes chain, returning a SynthesisResult with steps, citations, and gaps, and error handling. Missing explicit read-only/state-modifying indication, but otherwise transparent.

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-structured with sections, front-loaded with main purpose. Each sentence adds value; no redundancy. Length appropriate for the tool's complexity.

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 single parameter, no output schema, but description explains return type (SynthesisResult with steps, citations, gaps). Covers when to use, when not, error handling, and output structure. Complete for effective use.

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

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

Schema coverage is 100% with one parameter query described. The description adds value beyond schema by providing an example ('智驾无法激活') and explaining how the parameter is used (symptom/problem).

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 walks through a troubleshooting playbook in one shot, with a specific verb ('walk through') and resource ('playbook'). It distinguishes from siblings like recall/query via explicit when-to-use and when-not-to-use guidance.

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 use ('怎么排查 X') and when NOT to use ('general recall; use recall/query'), with clear alternatives and error handling advice ('rephrase the symptom or save a playbook page first').

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