personal-kg-mcp

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

No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It fails to mention that operations like 'repair', 'import', and 'merge_tags' are mutating or potentially destructive. There are no warnings about side effects, reversibility, or required permissions. For a multi-operation admin tool, this is a significant gap.

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

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

The description is a single sentence that efficiently lists all operations without unnecessary words. While it could benefit from bullet points, it is not overly verbose and front-loads the core purpose. The density is justified given the breadth of operations.

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

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

Given the complexity of a 9-operation tool with no output schema, the description is too thin. It explains what each operation does in a phrase but does not cover prerequisites, side effects, return formats, or safety implications. The schema helps with parameters but not with tool-level context, leaving the description incomplete.

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 provides 100% coverage with descriptions for all parameters, so the baseline is 3. The tool description adds no parameter-specific meaning beyond what the schema already contains; it only lists operation names. This is acceptable because the schema is thorough.

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 is an 'Unified admin tool for maintenance operations' and enumerates all supported operations. This distinguishes it from sibling tools like kg_search and kg_capture, which are domain-specific operations. The purpose is explicit and specific.

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 clear context for when to use each operation, e.g., 'health' for system status, 'backup' for data protection, 'export'/'import' for data migration. While it does not explicitly mention alternatives or exclusions, the admin/maintenance framing implies it is for system-level tasks rather than regular knowledge graph queries. This meets the standard for clear context without exclusions.

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

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

There are no annotations, so the description carries full burden for behavioral disclosure. It only states high-level operation purposes without revealing whether operations are read-only, potential side effects (e.g., export scope), parameter dependencies (e.g., path requiring start and end IDs), or output characteristics. This is a significant gap for a tool with multiple modes.

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 a single sentence that efficiently lists the four operations with crisp labels and purposes. No filler words, front-loaded with the core 'Unified analysis tool' phrase, and each clause earns its place. Extremely concise and well-structured.

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

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

For a tool with 7 parameters, 4 operations, no annotations, and no output schema, the description is too sparse. It does not explain return formats, prerequisites (e.g., path requires startId/endId), operation-specific caveats (e.g., clusters threshold effects, emerging windowDays semantics), or edge cases. This leaves significant gaps for an agent to safely 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 description coverage is 100%, and each parameter already has a detailed description including operation-specific prefixes. The description adds little beyond what the schema provides, though it does map operations to their conceptual meanings, which indirectly reinforces parameter usage. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a unified analysis tool and enumerates specific operations with concise purposes: 'clusters' for topic grouping, 'emerging' for trend detection, 'graph_export' for full export, and 'path' for finding connections. This is specific and differentiates the tool's capabilities, though it doesn't explicitly contrast with 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?

The description provides clear context for when to use each operation, effectively guiding selection among the four modes. It does not explicitly mention exclusions or alternatives among sibling tools, but the enumerated operations offer sufficient usage direction for an agent to choose appropriately.

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 discloses key automatic behaviors (relationship creation, tag normalization, session linking) which adds value, but it omits other side effects, return format, or error handling, leaving some gaps.

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 three sentences, front-loaded with the primary purpose, and contains no redundant or filler content. Every sentence adds meaningful 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?

Although the schema covers parameters thoroughly, the tool is complex (12 params) with no output schema or annotations. The description covers the use case and automatic behaviors but does not mention return values or potential side effects, leaving some contextual 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?

The input schema has 100% parameter descriptions, so the baseline is 3. The tool description adds no parameter-specific meaning beyond what the schema already provides, so no extra credit is warranted.

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 the primary capture mechanism for knowledge nodes, enumerates specific record types (decisions, progress, insights, questions, ideas), and positions it as the main entry point, effectively distinguishing it from sibling tools like kg_capture_session.

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 states explicitly when to use the tool ('Use this to record decisions, progress updates, insights, questions, and ideas') and frames it as the primary entry point, but it does not mention alternatives or exclusion cases.

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 implies a write operation ('captures') and persistence ('maintaining context'), but does not disclose side effects, permissions, whether existing summaries are overwritten, or the response format. This is a significant gap for a state-changing 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 two sentences, front-loaded with the core action, and both sentences provide useful context: one describing what the tool does, the other when to use it. There is no fluff or 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 six parameters and no output schema, so the description must cover behavior and outcomes. It explains purpose and usage context well, but does not mention what happens after capture (e.g., return value, retrieval method, or if it creates a new session entry). Adequate but with clear gaps.

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

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

Schema coverage is 100%, with detailed descriptions for all six parameters. The description mentions 'what was accomplished, artifacts created, and next actions' which loosely maps to summary, artifacts, and next_actions, but it adds no semantic detail beyond the schema. 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 uses a specific verb ('captures') and resource ('session summaries'), and adds context ('at the end of work sessions') that distinguishes it from generic capture tools like kg_capture. It clarifies the exact purpose and scope of the 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 explicitly states when to use the tool ('Use at the end of work sessions') and the intended outcomes (record accomplishments, artifacts, next actions). However, it does not explicitly mention alternatives or when not to use it, falling short of a full exclusionary guide.

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 for behavioral disclosure. It mentions 'Opens in browser' and generates an HTML file, which are key behaviors. However, it does not explicitly state whether the tool modifies any data or requires specific permissions. Since it is a diagnostic tool, the risk is low, but the description could be more explicit about the read-only nature and the generated file location (though that is covered in the schema).

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

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

The description consists of two concise sentences, front-loaded with the main purpose and followed by the key behavioral note about opening in the browser. Every word earns its place; no fluff or 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?

The description explains what the tool does, why it would be used, and what the output behavior is (HTML dashboard opened in browser). It lists the three diagnostic areas. Although no output schema exists, the description provides sufficient expectations. Slightly more detail on what the dashboard contains (e.g., visualizations or logs) would make it fully complete, but it is adequate for a diagnostic 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?

All three parameters have descriptions in the schema, covering their purpose and defaults (e.g., 'project' filter, 'output_path' custom location, 'open_browser' default true). The tool description does not add additional parameter detail, but the schema coverage is 100%, so the 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 it 'Generate a diagnostic HTML dashboard for debugging knowledge graph context selection, search results, and node visibility.' This is a specific verb+resource with three explicit areas of focus, distinguishing it from sibling tools like kg_search or kg_get_relevant_context which are functional operations rather than debugging aids.

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 a clear use case: 'to help understand why certain nodes are included/excluded from context.' This implies when to use the tool (when debugging context selection), though it does not explicitly mention alternatives or exclusionary conditions. The context is clear enough for an agent to infer appropriate usage.

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 hints at destructive behavior only through 'maintain for cleanup and rebuilding' but never discloses reversibility, side effects, what gets removed, or whether create involves validation. This is minimal 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?

Two sentences, front-loaded with the tool's unifying purpose and a compact list of supported operations. Every phrase adds information; no filler.

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

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

For a 9-parameter, 3-operation unified tool with no annotations and no output schema, the description is underspecified: it doesn't explain operation-dependent parameter groups, required fields beyond the schema, or return/error behavior. The operation list alone isn't enough 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?

The input schema has 100% description coverage, including operation-specific tags like '[create]' and '[maintain]', so the schema already carries parameter semantics. The tool description itself adds no parameter meaning beyond naming the operations, 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 description opens with 'Unified tool for relationship operations' and specifies three concrete verbs: 'create' to link nodes, 'list' to view relationships, 'maintain' for cleanup/rebuilding. This clearly distinguishes kg_edges from sibling node/tag/search tools as the relationship/edge manager.

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 clear per-operation guidance ('create' to link, 'list' to view, 'maintain' for cleanup/rebuilding), but does not name alternatives or explicitly say when not to use this tool relative to kg_link_session or kg_node. The context is clear but exclusions are absent.

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 of behavioral disclosure. It lists what the overview includes but does not state whether the operation is read-only, what the return format is, or any limitations. This is 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?

The description is two sentences, front-loaded with content and ends with usage 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?

For a one-parameter tool with no output schema, the description gives a good sense of what is included but omits details about the return structure. It is largely complete but could benefit from noting how the overview is presented.

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 fully describes the single parameter 'project' including normalization details. The description itself adds no extra parameter semantics, so the baseline score of 3 applies.

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

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

The description clearly states the tool provides a comprehensive overview of a project's current state and lists specific content areas (active focus areas, decisions, open questions, blockers, completed tasks). It is specific to a project state but does not explicitly differentiate from sibling tools like kg_get_relevant_context or kg_query_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 phrase 'Perfect for project status checks and planning' provides clear usage context. However, it does not mention when not to use this tool or alternatives, which would be needed 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It accurately indicates a read-only retrieval action and describes the nature of returned data, but does not explicitly state side-effect-free behavior, authentication needs, or how relevance is determined. This is adequate but not richly 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?

Two sentences with zero filler. The first sentence states the core function, the second adds practical usage context. Information is front-loaded and every word earns its place.

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

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

For a moderate-complexity tool with full parameter documentation and no output schema, the description covers the what, the output nature, and the when. It is complete enough for an agent to select and invoke correctly, though a note on return format or empty results would fully round it out.

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 parameter-level detail beyond the schema, but none is needed since all parameters are already well-documented in the input 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 opens with a specific verb and resource: 'Retrieves relevant past context for a given query.' It further clarifies the output content (summaries of decisions, insights, open questions), distinguishing it from sibling tools like kg_search or kg_get_project_state by highlighting proactive context injection.

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?

Clearly states the intended use case: 'Perfect for proactive context injection before starting work on a topic.' This gives explicit context for when to use the tool, though it does not name alternative tools or exclusion cases, which would elevate it to 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?

No annotations are provided, so the description carries the full burden. It discloses that the operation creates a relationship but omits side effects, return behavior, permission requirements, or whether existing relationships are overwritten. This is a mutation tool with minimal 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 description is two sentences, front-loaded with the core action, and the second sentence provides useful usage guidance without redundancy. Every word 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 simplicity (2 params, no output schema), the description covers the primary purpose and usage context. However, it lacks any mention of return values or prerequisites (e.g., whether nodes must already exist), and with no annotations to fall back on, it leaves some context gaps.

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

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

Schema coverage is 100% and descriptions for sessionId and nodeId already explain their roles. The description's mention of 'session node' and 'another knowledge node' adds no new semantic detail beyond the schema, so the 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 uses a specific verb ('Creates a relationship') and names both resources ('session node' and 'another knowledge node'), making the tool's function unambiguous. It distinguishes itself from siblings like kg_capture_session by focusing on linking rather than capturing.

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 usage context: 'Use to explicitly link work items, decisions, or progress to a specific session for better organization.' However, it does not explicitly mention alternative tools or when not to use, so it falls short of a 5.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states that tags are listed with usage counts and suggests use cases, but it does not disclose important behaviors such as whether zero-count tags are included (minCount defaults to 1), how results are sorted, or any potential rate limits or access requirements. This is a significant gap for a tool with no annotation support.

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 two sentences long, front-loaded with the core function, and follows with usage guidance. Every word earns its place, making it concise and well-structured.

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

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

Despite having no annotations or output schema, the description adequately covers purpose and use cases for a relatively simple read-only list tool. The schema covers all parameters with defaults and constraints. However, it does not describe the return structure or any edge cases, which would be nice but is not critical for a tool of this simplicity.

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 parameters are fully documented in the schema. The description does not add any additional semantic meaning beyond what the schema already provides, and the baseline of 3 applies.

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

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

The description uses a specific verb ('Lists') and clearly identifies the resource ('all tags in the knowledge graph') with a distinctive detail ('with usage counts'). It is unambiguous and distinguishes itself from sibling tools like kg_search or kg_edges, which serve 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 use the tool ('discover available tags, find inconsistencies, or identify commonly used categories') but does not mention when not to use it or suggest alternatives. This provides clear context but lacks explicit exclusions.

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

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It explains that 'get' retrieves relationships, 'delete' removes a node, and 'find_similar' finds semantically similar nodes, but it does not mention consequences like irreversible deletion or relationship handling beyond what the schema already documents via deleteEdges.

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 at two sentences, front-loads the tool's purpose, and structures the operations in a clear list. Every sentence contributes value 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 description adequately covers the three operations and their high-level behaviors, but it lacks details about return values or output structure. Given the tool's moderate complexity and the absence of an output schema, a bit more context (e.g., what each operation returns) could improve completeness, though the current level is sufficient for basic 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?

The schema already has 100% parameter coverage, so the description adds little beyond the schema. It does not clarify parameter interactions or operation-specific applicability beyond the schema's own descriptions. The baseline of 3 is appropriate because the description does not harm but also does not enhance the schema's semantics.

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

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

The description clearly states the tool's scope ('unified tool for node operations') and enumerates the three supported operations with their specific actions. This provides a clear sense of what the tool does, though it does not explicitly distinguish itself from sibling tools like kg_update_node.

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

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

The description implies usage for node retrieval, deletion, and similarity search by listing the operations, but it does not provide explicit guidance on when to choose this tool over alternatives (e.g., kg_update_node for updates, kg_search for general search). The usage is inferred rather than stated.

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

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

With no annotations, the description carries the transparency burden. It discloses the stale-after-3-days rule and implies a read-only list operation via the verb 'Lists,' but it does not explicitly state the absence of side effects, output format, or ordering. It adds some context but lacks full behavioral transparency.

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 two sentences, front-loaded with the core purpose, and every sentence earns its place. It is concise, clear, and free of filler.

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

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

For a simple list tool with three optional parameters and no output schema, the description gives a solid overview: purpose, usage, and a specific aging rule. It does not fully describe return values or ordering, but the absence of an output schema makes that less critical. Overall, it is fairly complete.

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

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

Schema coverage is 100%, so the parameters are already well-documented. The description adds only marginal context by referencing 'aging information' and the stale threshold, which the include_stale parameter description also covers. No new syntax or format details are provided.

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 'Lists' and the resource 'unresolved questions,' adding the specific scope of 'aging information' and the stale threshold. This distinguishes it from sibling tools like kg_resolve_question, which resolves questions, and kg_search, which searches broadly.

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 a clear use case: 'Use to track what needs follow-up and identify forgotten questions.' However, it does not explicitly mention alternatives or when not to use this tool, such as noting that kg_resolve_question should be used for resolving questions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It tells what the tool does but does not reveal any behavioral traits such as read-only nature, output format, limitations, or side effects. For a query-like tool, it should at least indicate that it does not modify data or describe what the result includes.

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 two sentences long, front-loaded with the core action, and contains no filler. Every sentence earns its place: the first explains what it does, and the second gives a usage context.

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

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

The tool is simple (one required parameter) and the description covers the purpose and usage. However, with no output schema and no annotations, the description should provide more context about what the tool returns (e.g., a list of related nodes or a graph) and any behavior assumptions. It is adequate but leaves 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?

The schema already provides 100% coverage for the single parameter 'topic' with a clear description and examples. The tool description adds no additional meaning beyond what the schema provides, so the 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 what the tool does: 'Reconstructs context around a specific topic by analyzing related knowledge nodes.' It uses a specific verb ('reconstructs') and resource ('context around a topic'), which is clear and distinct. However, it does not explicitly differentiate itself from sibling tools like kg_get_relevant_context, which may serve a similar 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?

The description says 'Use to understand the full context and background of a particular subject area,' which provides clear guidance on when to use this tool. It lacks explicit exclusions or alternatives, but the stated use-case is specific and helpful.

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 of disclosing side effects. It clearly states the mutation ('Creates a resolved_by relationship'), which is useful. However, it does not disclose reversibility, idempotency, or whether the question must be in a specific state, leaving some behavioral uncertainty for a write operation.

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 two sentences long, front-loads the core purpose, and includes no filler. Every word contributes to understanding the tool's function and effect.

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 three parameters, no nested objects, and no output schema, the description provides adequate context: what it does, what relationship it creates, and what types of nodes are eligible. It does not explain return values or edge cases, but these are not critical for correct invocation given the schema covers parameters.

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

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

Schema description coverage is 100%, so the schema already explains all parameters well. The description only echoes what the schema says about 'resolved_by_id' being a decision/insight, adding no meaningful extra semantics. 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 uses a specific verb ('Marks... as resolved') and clearly identifies the resource (question node) and the mechanism (linking to a decision/insight and creating a 'resolved_by' relationship). It distinguishes this from generic tools like kg_update_node or kg_link_session by focusing on the resolution semantics.

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 implies the use case: when a question has been answered by a decision or insight and should be marked resolved. It provides context but does not explicitly state when not to use it or name alternative tools, so it misses the top score for explicit exclusions.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It does describe the behavioral characteristics of each mode (e.g., 'keyword/tag filtering with ranking', 'AI-powered meaning-based search', 'date-based queries'), which adds some value. But it does not disclose return format, pagination, error behavior, or explicitly state read-only nature. This is 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?

The description is two compact sentences, front-loading the core purpose ('Unified search tool') and then efficiently summarizing the three modes and default recommendation. Every word earns its place; no fluff or 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 (13 parameters, mode-dependent behavior, no output schema), the description is somewhat underspecified. It explains the modes at a high level but does not provide guidance on selecting between modes for common use cases, expected result structure, or interaction with sibling tools. It is not grossly incomplete, but it leaves meaningful gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the high-level mode concept and default behavior, which helps users understand how the mode-dependent parameters (like query, tags, start/end) relate to each other. This goes beyond the individual parameter schemas.

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 function with a specific verb ('search'), the resource ('knowledge nodes'), and differentiates itself from siblings by calling itself 'Unified search tool' and listing three distinct modes (text, semantic, time_range). This makes it immediately distinguishable from other kg_* 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?

The description provides clear context on when to use the tool: it is the 'unified search tool' for finding knowledge nodes, with a default mode recommendation ('semantic' for best results). However, it does not explicitly mention alternatives or exclusions relative to sibling tools like kg_get_relevant_context or kg_query_context.

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

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

No annotations are provided, so the description must carry the transparency burden. It discloses that the tool loads comprehensive context and lists what it includes, implying a read-oriented operation, but it does not clarify side effects, permission requirements, or session state changes. This adds some value beyond the schema but lacks rich behavioral detail.

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 punchy sentences with the usage imperative front-loaded. No filler; every phrase contributes either usage guidance or a content summary.

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 conveys the core purpose and content categories, and the schema documents the parameters and modes. However, because there is no output schema, the description does not fully explain the response structure or how 'discovery mode' and 'compact' affect the output, leaving some ambiguity for a 5-parameter 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 covers all 5 parameters with descriptions, so the description need not repeat parameter semantics. The description adds no parameter-level details, but with 100% schema coverage, the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a session-start context loader, listing specific content categories (recent work, active questions, blockers) and framing it as a continuity/warmup mechanism. It does not explicitly name sibling alternatives, but the verb+resource combination and 'session warmup' framing distinguish it from generic searches or project-state queries.

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 guidance ('Start every session with this tool!', 'Essential for maintaining continuity between work sessions'). It does not offer exclusions or mention alternative tools, so it stops short of full 5-level 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?

With no annotations, the description carries the transparency burden. It usefully discloses that updates are partial ('only specified fields are changed'), which is valuable behavioral context. Yet it says nothing about permissions, reversibility, return values, or failure modes—important gaps 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?

Two sentences, front-loaded with the core action and supported fields. Every word serves a purpose, and the partial-update clarification earns its place. This is appropriately concise.

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

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

Given the tool's moderate complexity (8 params, no annotations, no output schema), the description plus the fully described schema is largely complete. It states what the tool does, what can be changed, and the partial-update behavior. A mention of response/error behavior or permissions would make it fully complete.

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

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

The input schema already describes all 8 parameters, so schema description coverage is 100%, which sets a baseline of 3. The description adds only the general partial-update note, not field-specific meaning, so it neither improves nor harms the parameter semantics.

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

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

The description opens with 'Updates an existing knowledge node,' clearly identifying the specific verb and resource. It also enumerates the editable fields (content, tags, importance, visibility) and notes partial-update support, which distinguishes it from sibling tools like kg_capture or kg_node.

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 'Use to modify content, tags, importance, or visibility of a node,' giving a clear condition for use. However, it does not mention when not to use the tool or name alternative tools, so it stops short of a 5.

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