Knowledge Forest MCP

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

Annotations already cover the basic mutation profile (not read-only, not idempotent, not destructive). The description adds meaningful behavioral context beyond those annotations: source-visible material never changes mastery state, which clarifies the tool's side effects on learning state and is not derivable from the schema or annotations.

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

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

Two sentences with no filler. The primary action is front-loaded, and the important behavioral caveat about mastery state is placed second, following naturally from the action.

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

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

The description is adequate for a straightforward append operation, and the schema covers required fields and constraints. Still, it does not clarify what happens for closed-book versus source-visible entries beyond the one guarantee, nor what the operation returns, which leaves some practical ambiguity for an 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 0%, so the description must compensate. It adds meaning for 'kind' by enumerating the four values and for 'source_visibility' by explaining the mastery-state implication. However, it does not clarify 'node_id', 'content', or the optional 'sources' array, leaving significant parameter semantics to the schema alone.

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

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

The description states a specific verb ('Append') and resource ('to a node'), and enumerates the exact kinds of content: note, reflection, source, or exercise. It also adds a distinguishing scoping rule about source-visible material, which helps separate it from related learning-state 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 implies when to use the tool—when appending learning material to a node—and its note that source-visible material never changes mastery state hints at one selection criterion. However, it does not explicitly name alternatives like update_node_learning_state or record_verification, nor state when not to use 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?

Annotations already indicate this is not read-only and not idempotent, so 'Persist' is consistent. The description adds valuable behavioral context beyond annotations: search first to avoid duplicatesainer, and only reuse truly equivalent concepts. It does not contradict the annotations.

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

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

The description is two sentences with three distinct, compact instructions: persist, search first, and only reuse when truly equivalent. Every clause earns its place and the most important action is front-loaded.

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

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

For a complex nested tool with no output schema, the description gives the essential search-reuse workflow and the core persistence action. However, it omits return/error expectations and does not clarify what 'minimal sufficient' means in practice, so it is adequate but not fully complete for invoking the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it only offers conceptual labels like 'goal,' 'branches,' and 'prerequisite-linked knowledge nodes.' It does not explain the required fields, temp_id linkage, or how to construct a valid nested goal tree, leaving the agent without enough parameter-level guidance.

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 'Persist one observable goal, its branches, and prerequisite-linked knowledge nodes,' a specific verb+resource statement that clearly communicates what the tool creates. This distinguishes it from sibling read, update, diagnose, and export tools even without opening the schema.

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

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

The description explicitly says 'Search first,' establishing a clear precondition to search the knowledge base before persisting a goal tree. The reuse_node_id guidance adds a useful when-to-reuse rule, though it does not name sibling tools directly or fully spell out when-not-to-use 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?

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those annotations by stating the operation is deterministic and does not call a model, which clarifies expectations about variability and external dependencies. There is no contradiction with 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?

Two sentences with no filler. The first sentence front-loads the core behavior and outcome, and the second adds an important behavioral distinction. Every part 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 simple deterministic read-only tool, the annotations carry much of the safety context. However, with no output schema, the description does not indicate what the tool returns or how to consume the recommendation, and it lacks explicit usage guidance relative to siblings. An agent can invoke it correctly but may not know what to do with the result.

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

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

Schema description coverage is 0%, and the description never mentions node_id or how it should be used. The parameter name is reasonably self-explanatory, which prevents a 1, but the description contributes no additional semantic meaning or usage detail for the required parameter.

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

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

The description states a specific verb (identify) and resource (prerequisite, depth, and evidence gaps), and attaches a concrete outcome (recommend the next learning action). It also distinguishes itself from model-based operations with 'It does not call a model,' which helps separate it from siblings.

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

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

The context is implied: an agent would call this when it needs to diagnose gaps and decide a next action for a node. However, the description never explicitly says when to use this tool versus alternatives such as get_node_context, search_knowledge, or update_node_learning_state, and it provides no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by clarifying that the export is portable and includes append-only learning records and evidence, which goes beyond what the annotations alone express.

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 well-structured sentence. It front-loads the action and resource, and every qualifier ('complete', 'portable', 'append-only') adds meaningful scope 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?

For a no-argument, read-only export operation, the description sufficiently explains what the tool returns in broad terms. It does not explicitly specify the output format or file type, but 'portable' and the strong annotation set make this adequate for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the description does not need to explain parameter meanings. This matches the baseline for a parameterless tool, and the schema already covers all 0 parameters at 100% coverage.

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

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

The description states a specific verb ('Read') and resource ('complete portable forest state'), and further specifies it includes append-only learning records and evidence. This clearly distinguishes it from siblings like forest_overview and search_knowledge.

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 this is for obtaining a full state snapshot rather than a summary or search result, but it does not explicitly state when to choose this tool over alternatives like forest_overview or get_learning_queue.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the 'never modifies learning state' statement is largely redundant. The description does add useful context about what content is read, but no new behavioral traits beyond the annotations are disclosed.

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

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

The description is two short, front-loaded sentences with no wasted words. It states the return content and the invocation guidance in an efficient, easily parseable way.

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 read-only tool with one optional parameter and no output schema, the description is complete. It tells the agent what the tool does, what it returns, when to call it, and confirms it is safe to invoke.

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

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

Schema coverage is 100%, and the single optional goal_id parameter is already described in the schema. The description adds no further parameter-level guidance, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Read') and names the exact resources it returns: goals, mastery counts, and next ready knowledge nodes. This clearly distinguishes it from sibling tools like search_knowledge or get_learning_queue, which address different concerns.

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 instructs to 'call this first', giving actionable routing guidance for an agent. It does not name alternatives or exclusions, but the first-call directive and read-only emphasis provide enough context for correct 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the inclusion of both ready and prerequisite-blocked nodes and the ordering by readiness and importance, but it doesn't explain how readiness is determined or how ordering is implemented in practice.

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, front-loaded sentence that conveys the core behavior without filler. Every phrase contributes meaning: 'ready and prerequisite-blocked nodes' specifies scope, and 'ordered by readiness and importance' specifies ordering.

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 no output schema, no parameter descriptions, and only implied usage guidance, the definition is incomplete. It omits what the returned nodes look like, how goal_id filters results, and how to interpret prerequisite-blocked nodes. The two parameters are otherwise opaque to an 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 0%, and the description does not compensate: neither 'limit' nor 'goal_id' is explained in words. An agent cannot infer from the definition what goal_id does (e.g., filter by goal) or how limit affects the returned queue, since the schema only provides type, default, and bounds.

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

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

The description clearly states a specific verb ('Return'), a specific resource ('learning queue'), and the exact content scope ('ready and prerequisite-blocked nodes, ordered by readiness and importance'). This distinguishes it from sibling tools like get_node_context or diagnose_node, 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?

Usage is only implied: the phrase 'actionable learning queue' suggests this is for retrieving nodes that are ready or blocked by prerequisites. However, there is no explicit when-to-use guidance, no stated condition for choosing this over alternatives like forest_overview or get_node_context, and no exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds a behavioral nuance by mentioning a 'deterministic diagnosis', indicating that diagnosis is computed rather than arbitrary, which is useful context. However, it does not elaborate on return format, error behavior, or data consistency, so the added value beyond annotations is modest.

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, front-loaded sentence that efficiently lists all returned components with no redundant words. Every element earns its place, making it easy to parse quickly.

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 outlines the full set of returned components (goal memberships, prerequisites, dependents, learning entries, verification history, deterministic diagnosis), giving a clear picture of the output. No output schema exists, so this list effectively serves as the return contract. It does not mention potential errors or pagination, but for a single-node read tool with a single parameter, this is 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 0% and the description does not explain the 'node_id' parameter at all. While the parameter name is self-explanatory, the description fails to explicitly map 'node_id' to the node being read, nor does it add constraints or format details. With zero schema documentation, the description carries the full burden and does not meet it.

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

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

The description states a specific action ('Read') and names the resource (knowledge node) along with the full list of components (goal memberships, prerequisites, dependents, learning entries, verification history, deterministic diagnosis). It distinguishes itself from sibling 'diagnose_node' by explicitly including diagnosis as part of the context, preventing ambiguity.

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

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

The description implies that this tool is for reading comprehensive node context, but it does not provide explicit guidance on when to use it versus alternatives like 'search_knowledge' or 'diagnose_node'. No when-not-to-use or exclusionary criteria are given, leaving selection largely to the agent's inference.

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

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

The description adds meaningful non-obvious behavior: mastery only advances under demonstrated, novel, unassisted, closed-book conditions, and acceptance is computed server-side. This goes beyond the sparse annotations and helps the agent predict 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?

Two tight sentences with the core action first and no filler. Every phrase adds information: what is recorded, when mastery advances, and that the server decides acceptance.

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 eight required parameters, no output schema, and no rich annotations, this description is incomplete. It omits return behavior, how to structure evidence fields, and how this tool relates to sibling learning-state tools, leaving the agent to infer too much.

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

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

With 0% schema description coverage, the description must compensate. It maps core criteria like 'demonstrated, novel, unassisted, closed-book' to outcome, novel_prompt, assisted, and closed_book, but it does not explain prompt, response, rationale, or node_id beyond their self-evident names.

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

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

The description uses a specific verb ('Record') and specifies the resource ('one verification attempt'), while the title clarifies it concerns closed-book mastery evidence. It clearly distinguishes this from generic state-updating tools like update_node_learning_state.

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 what the tool does but gives no guidance on when to prefer it over siblings such as update_node_learning_state or append_learning_note. There is no when-not-to-use context or alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that by specifying that results include reuse context and current mastery state, which helps an agent anticipate what the search returns.

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, efficient sentence with no wasted words. It front-loads the main action, includes workflow context, and summarizes result content 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?

For a simple two-parameter search tool, the description covers purpose, workflow, and result contents reasonably well. However, the complete absence of parameter-level guidance and the lack of an output schema leave some ambiguity about query formatting and how 'limit' behaves.

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

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

Schema description coverage is 0%, and the description does not explain the 'query' or 'limit' parameters. The parameter names and schema constraints are somewhat self-explanatory, but the low coverage means the description should compensate, and it does not.

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

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

The description states a specific action ('Search canonical nodes') and a resource, and adds what the results contain ('reuse context and current mastery state'). It is clear about the tool's purpose, though it does not explicitly name sibling tools to differentiate itself.

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 'before creating a goal tree' gives clear workflow context and signals when this search should be invoked. It does not explicitly mention alternatives or when not to use it, but the usage context is strong enough to guide 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?

Annotations already provide readOnly=false, destructive=false, and idempotent=true. The description adds the constraint that this is for non-verified workflow states, which clarifies the behavioral scope. It does not contradict the annotations and provides useful context about what the mutation does and its boundary (not marking mastery).

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 exactly two sentences with no filler. It front-loads the primary purpose and adds the critical exclusion in a clear, direct manner. 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 tool with 4 parameters, 2 required, and 2 enums, the description covers only the broad purpose and a single exclusion. It does not explain parameter semantics, typical usage contexts, or how it fits with sibling tools beyond record_verification. The agent would need to inspect the schema thoroughly to use this correctly, which the description should partially compensate for.

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

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

With 0% schema description coverage, the description carries the full burden for parameter explanation. It mentions 'depth' and 'workflow state' but does not explain the meaning of 'desired_depth' vs 'status', the role of 'reason', or whether they can be set together. The agent is left without guidance on how to fill the parameters correctly.

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

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

The description states a specific verb ('Set') and resource ('learner-selected depth or non-verified workflow state'), which clearly identifies the tool's function. It also explicitly distinguishes itself from record_verification by stating what it cannot do, making it easy for an agent to differentiate from the sibling that handles mastery.

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 when-not-to-use and an alternative ('cannot mark mastery; use record_verification for that'). However, it does not explicitly state when to use this tool (e.g., when updating a node's depth or workflow state), leaving that to inference. The exclusion is explicit, but the positive usage condition is implied rather than stated.

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