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

With no annotations, the description carries the full burden and does so: side effects none, auth none, rate limits/stdio context, content truncation to 5000 chars, and enumerated error cases (missing inputs, not found with search suggestion, path outside lessons/). It also discloses non-obvious behavior like canonical-set dedup matching and traversal validation.

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

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

Front-loaded with purpose, then usage, then input/output/error/safety facts in a logical order. It is dense and every clause is informative, though the trailing 'Side effects / Auth / Rate limits' tail is slightly list-like and longer than strictly necessary.

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

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

No output schema exists, so the description correctly documents the return shape ({path, content}) and the truncation cap. It covers errors, precedence, and safety, leaving an agent with essentially everything needed to call it correctly.

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

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

Schema coverage is 100%, but the description adds substantial semantics beyond it: exactly one of path/id, path precedence when both are given, handler returns {error} when neither is given, path traversal validation, and that id matches only the canonical set while mirrors/translations require an explicit path. These are real behavioral constraints not derivable from the schema.

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

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

States a specific verb (Fetch) and resource (one public MisakaNet lesson) with the two addressing modes (path or lesson ID). It explicitly contrasts itself with the sibling misakanet_search by ruling out broad discovery, so an agent can distinguish them without opening a schema.

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

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

Gives explicit when-to-use (after misakanet_search returns a promising result, or when a lesson is explicitly referenced) and when-not (broad discovery), naming the sibling that covers the excluded case. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so: read-only, no side effects, no local writes, no auth, proxy with no local fallback, rate-limit behavior, and named error cases (missing_lesson_reference, hosted_endpoint_unavailable). It even warns that an empty events list would be a different, wrong answer — a genuinely useful behavioral caveat.

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?

It is long but front-loaded and clearly sectioned (purpose, params, semantics, returns, errors, side effects, auth, rate limits). A few statements are redundant — the return shape is stated twice and the error cases are restated — which costs it a point against a tighter version.

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 output schema and no annotations, the description specifies the return object shape, the evidence-level enum, error cases, and the absence of a fallback. An agent has everything needed to call it correctly and interpret 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 coverage is 100% and the schema already gives examples for both parameters, so baseline is 3. The description adds real meaning beyond the schema: that lesson_path is normalized to an id 'the same way', that either satisfies the requirement, and that passing neither is refused before any network call, which is not encoded in the schema.

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

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

The description opens with a specific verb+resource ('Return evidence of a lesson being reused (E4 signals)') and enumerates exactly what the evidence comprises: helpful votes, regression-benchmark citations, cross-node confirmation. It also clarifies its semantic identity versus the historical name, so an agent can distinguish it from siblings like get_lesson or search without opening a schema.

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

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

It states the decision context explicitly ('Use to check whether a lesson is proven by real usage, not just self-reported') and names the semantic equivalent sibling ('misakanet_get_my_events'), plus the refusal condition when neither argument is given. When-to-use is unambiguous.

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

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

With no annotations provided, the description fully carries the behavioral burden and does so extensively: matching is lexical/BM25 not embeddings, `domain` is a hard filter with silent zero-result behavior, `top_n` is silently clamped, fields are truncated, empty results are not tool failures, side effects/auth/rate limits are declared, and the deployment limitation is disclosed. This goes well beyond what any structured field could provide.

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 long but densely informative and structurally organized around decision-relevant sections: usage, parameter semantics, output, errors, side effects, and environment. The proactive usage guidance is front-loaded, and every sentence contributes operational value for a tool with meaningful edge cases.

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 no annotations, the description is complete: it covers input semantics, output shape, zero-result interpretation, error behavior, retry guidance, side effects, auth, rate limits, and the context of local vs hosted deployment. An agent has everything needed to select and invoke this 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: `task` must be phrased in the vocabulary of emerging errors rather than intents, `domain` is a closed-vocabulary hard filter that returns zero rather than erroring, and `top_n` has clamping and truncation behavior. It materially improves the agent's ability to supply correct argument values.

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

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

The description states a specific purpose and action: retrieve failure-memory context BEFORE starting a task, positioning it as the proactive counterpart to misakanet_search. It explicitly names the sibling it is not and the trigger condition for each, so an agent can distinguish them without opening schemas.

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

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

It gives explicit when-to-use guidance ('call this BEFORE starting a task') and when-not-to-use guidance ('call misakanet_search once a specific error has actually appeared'). It also provides actionable parameter-level usage advice: pass concrete nouns/tools/error words rather than goals, and omit `domain` unless the exact vocabulary is known.

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 fully carries the behavioral burden. It discloses that the tool is read-only with no side effects, no auth, local stdio only, error behavior for missing intent, output shape, and subtle interpretation details such as high risk_level with empty matched_lessons.

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

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

The description is front-loaded with purpose and usage, then labels input semantics, output shape, error cases, side effects, auth, and rate limits. Despite its length, every section provides actionable information and no sentence is wasted.

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 no output schema and no annotations, so the description must supply return format, safety profile, and operational context. It does all of this, including the output JSON structure, error case, side-effect absence, auth, and rate limits, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description repeats the examples and adds the required/optional distinction, but does not provide syntax, format, or constraints beyond what the schema already contains.

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 begins with a specific verb and resource: 'Check risk level before executing high-risk operations.' It then clarifies that the tool matches agent intent against lesson triggers and risk profiles, distinguishing it from sibling tools like misakanet_search or misakanet_get_lesson.

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

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

It gives concrete when-to-use examples: 'before RAG builds, WSL/GPU tasks, bulk imports, or any operation that might fail.' It does not explicitly state when not to use the tool or name a sibling alternative, but the triggering conditions are 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?

With no annotations, the description carries the full burden and delivers: side effects (persists a record in usage_meter), auth (none), rate limits (one per session), error cases (invalid_client_id), and a reuse contract. It even discloses the critical security property that client_id functions as a secret key because the server returns a stored token deterministically.

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?

Dense but well-structured with labeled sections (Input semantics, SECURITY, Output schema, Error cases, Side effects, Auth, Rate limits). The core purpose and the key/warning are front-loaded, and no sentence is 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?

Because no output schema exists, the description compensates by naming the returned JSON shape and the reused flag. It covers auth, rate limits, error paths, side effects, and the security caveat, leaving nothing an agent needs to call it correctly unstated.

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 already 100%, but the description adds semantics the schema does not: client_id is a key rather than a label, calling with it yields reused=true and the same node, and omitting it mints a new node each call. It also supplies generation guidance (random UUID, not hostname-derived), which is actionable beyond the schema text.

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

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

States a specific verb ('Register an agent') and the concrete payoff ('receive a node_id and token for unlimited remote MCP access'). It also positions itself against siblings by clarifying that only write tools require registration while reading tools do not.

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

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

Explicitly states when to use it (remote HTTP MCP, before other calls, to get a token) and when not to (reading needs no registration, local stdio is unlimited). It also tells the agent where the token goes in subsequent calls.

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

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

With no annotations, the description carries full behavioral disclosure. It explicitly states 'Side effects: none. Auth: none. Rate limits: local stdio process only; callers should keep result counts small.' It also covers error cases, output format, and the vector similarity null when the optional backend is unavailable. This is thorough and 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?

The description is long but well-structured and front-loaded with the core purpose and usage context. It then systematically explains parameters, output, errors, and side effects. While it could be tightened, every section adds necessary information, and the organization makes it scannable.

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

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

Given the tool's complexity (10 parameters, no output schema), the description covers all essential aspects: query requirements, filtering options, progressive disclosure levels, error cases, output format, side effects, auth, rate limits, and privacy constraints. It even explains when to use the sibling for full content. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the auto-detection of 'kind' from query intent, the progressive disclosure trade-offs of 'detail', and the interaction of weight parameters (though the schema already mentions the sum constraint). It enriches understanding of when and how to set 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 opens with a specific verb and resource: 'Search MisakaNet's public failure-lesson index by error text, keyword, or topic.' It clearly states the scope (discovery, not retrieval by ID) and explicitly contrasts with the sibling misakanet_get_lesson, which is for full content when an ID is known. This makes the tool's role unambiguous.

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

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

It provides explicit when-to-use guidance: 'Use when you need to discover relevant lessons and do not already know a lesson ID.' It also tells when not to use it: 'Do not use for private log collection; search only with redacted snippets.' It names the alternative for full content: 'Use misakanet_get_lesson for full content.' No inference is required.

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

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

No annotations are present, so the description must carry the burden, and it does: it declares the side effect (writes to data/contribution_queue.jsonl), error cases (missing problem, duplicate submission), output schema fields, auth none, and rate limits. This goes well beyond 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?

Every sentence adds distinct information, and the internal labels (Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits) make scanning easy. The most important purpose and usage information is front-loaded.

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

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

For a tool with no annotations and no output schema, the description covers all invocation-critical aspects: inputs, output shape, errors, side effects, auth, and rate limits. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the default for kind (missing_lesson) and the required/optional split. It omits 'source' from its summary, but the schema already documents it, so this is a minor gap.

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

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

The description opens with a specific verb ('Submit') and resource ('a failure-case intake') and immediately states the triggering conditions ('no matching lesson exists or a lesson was stale/incorrect'). This clearly separates it from sibling tools like misakanet_search and misakanet_write_lesson.

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

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

It gives explicit 'Use after misakanet_search fails...' and 'when the user resolved a problem not yet documented' triggers. It does not name exclusions or contrast with other submission tools like submit_usage/write_lesson, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: error cases (missing lesson_id), side effects (local placeholder only, remote disabled via MISAKANET_USAGE_DISABLE_REMOTE=1), auth (none), and rate limits (local stdio only). This is unusually complete disclosure for an unannotated 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?

Information-dense and front-loaded with the core action, then ordering, then semantics, then errors/side effects/auth/limits. Dense but each segment earns its place; the '[Experimental]' tag is useful signal. Slightly list-heavy but not padded.

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

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

For an unannotated mutation-style submit tool with no output schema, the description covers purpose, timing, parameters, errors, side effects, auth, and rate limits. The main gap is that it describes the output shape informally ('JSON with {lesson_id, tool, outcome, status}') without an actual output schema, but this still conveys what the agent receives.

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 all three parameters are already documented in the schema. The description restates the semantics (lesson_id required, tool is the calling client, outcome should be solved/partial/not-helpful) but adds no format or constraint detail beyond the schema. Baseline 3 applies when 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?

States a specific verb+resource: 'Record that a public lesson helped with a problem.' The experimental bracket and the explicit timing ('Call this AFTER a lesson has been used and the outcome is known') distinguish it from siblings like misakanet_usage_status and misakanet_write_lesson.

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 call (after outcome is known) and names the prerequisite check tool misakanet_usage_status before submitting. This is a clear ordering constraint that routes the agent 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 are provided, so the description carries the full burden and does so: it declares side effects (none), auth (none), rate limits (none), and error behavior ('returns defaults on failure'). It also describes the return payload field-by-field, which is critical since no output schema exists.

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?

Purpose and usage are front-loaded, then tightly grouped labeled blocks (Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits). Dense but zero-waste; every clause answers a question an agent would otherwise have to guess at.

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 a single optional parameter, no output schema, and no annotations, the description compensates fully by describing the returned JSON fields, failure behavior, and safety profile. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds workflow-level meaning the schema lacks: where the token value comes from (misakanet_register), the 'token:xxx' format, and the 'anon:mcp-default' fallback. It stops short of explaining any validation or format errors for a malformed user string.

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

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

States a specific verb and resource ('Check current usage status and remaining quota') and immediately distinguishes itself from siblings by naming misakanet_submit_usage and misakanet_register as the tools it feeds into. An agent can place it in the workflow without opening any schema.

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

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

Gives explicit when-to-use ('Use before calling misakanet_submit_usage') plus a conditional branch ('Call misakanet_register if is_registered is false and you need write access'). Both the trigger and the follow-up alternative are spelled out, leaving nothing to inference.

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

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

With no annotations provided, the description carries the full burden, and it excels: it discloses the side effect (writes to data/contribution_queue.jsonl), auth requirements, error cases, the 75 quality threshold, duplicate-submission behavior, and the output shape. This is strong behavioral disclosure for a mutating 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 dense but well organized: a front-loaded purpose sentence, a usage condition, then terse semicolon-separated sections for input semantics, output schema, errors, side effects, auth, and scope. Every clause carries distinct, valuable information without 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?

This is a 9-parameter write operation with no annotations and no output schema, yet the description covers required/optional inputs, output fields, error conditions, side effects, auth, and process scope. It gives an agent everything needed to decide whether and how 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?

Schema coverage is 100%, so the schema already documents all parameters; the description's required/optional summary adds only marginal convenience. However, there is an inconsistency: it lists token as optional while also saying a registered token is required and the schema property notes it is required for write_lesson, which slightly undermines the added value.

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 object: 'Submit a complete, structured failure lesson.' It also defines the precise scope—lessons documenting the full failure→root cause→fix→verification chain—which clearly separates this from the search, get, usage, intake, preflight, and registration siblings.

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

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

It clearly states when to use the tool: 'after resolving a problem and documenting the full failure→root cause→fix→verification chain.' It also notes the auth prerequisite (registered agent token, not anonymous), but it does not explicitly mention alternatives or when not to use the tool.

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