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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers side effects ('none'), authentication ('none'), rate limits, error cases, and output truncation to 5000 characters, giving the agent a complete behavioral picture.

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 the core purpose, followed by compact, information-dense sections for usage, input, output, errors, side effects, auth, and rate limits. Every sentence earns its place without unnecessary 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?

Even without an output schema, the description explains the return value format and truncation behavior. It also covers error cases, side effects, auth, and rate limits, making it fully actionable for an agent selecting and 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 coverage is 100%, so the baseline is 3. The description adds meaningful relational semantics by stating 'provide either path or id,' which clarifies that the parameters are alternatives rather than independent optional fields. This is valuable beyond the individual parameter descriptions.

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

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

The description states a specific verb and resource: 'Fetch one public MisakaNet lesson by repository path or lesson ID.' It clearly distinguishes from siblings like misakanet_search, which is for discovery, and misakanet_write_lesson, which is for writing.

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

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

The description explicitly tells the agent when to use this tool: after misakanet_search returns a promising result, or when a lesson is explicitly referenced. It also states a clear exclusion: 'do not use it for broad discovery,' which prevents confusion with search tools.

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

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

No annotations are provided, so the description carries the full behavioral burden — and it delivers extensively: lexical/BM25 matching rather than embeddings, silent clamping of top_n to 10, 200-character field truncation, zero-lessons-with-no-error behavior for unknown domains, no auth/rate-limit/network dependency, and results bounded by checkout freshness. This is exactly the operational context an agent needs and far beyond what annotations would normally supply.

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 every paragraph earns its place and the structure is navigable: a call-timing rule first, then a 'How X behaves' subsection per parameter, then return semantics, then environment constraints. It restates a couple of schema facts (clamping, 200-char truncation) but always adds the underlying rationale; it loses a point only because a strict editor could trim those redundancies.

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

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

With no annotations and no output schema, the description covers the return shape ({task, lesson_count, lessons, context_block}), the ready-to-inject nature of context_block, the precise meaning of lesson_count 0, environment constraints (stdio-only, checkout-local data), and the failure semantics for bad domain values. Nothing an agent needs in order to call this correctly is left to inference.

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, but the description adds substantial meaning: for task it gives negative examples ('make it faster' retrieves nothing) and the concrete-nouns/error-words rule; for domain it names the closed-vocabulary source (data/domains.json) and a diagnostic hint tying empty results to the filter; for top_n it adds a cost-benefit breakpoint (~5 matches). The description clearly exceeds what the schema alone communicates.

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 by positioning this as the 'proactive half of the pair' whose job is putting failure-memory into context before a task starts, and it explicitly differentiates itself from misakanet_search ('call misakanet_search once a specific error has actually appeared'). The retrieval function — matching a task against the lesson corpus — and its operational role are unmistakable, and sibling distinction is a stated feature, not something an agent must infer.

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

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

Provides explicit when-to-use ('call this BEFORE starting a task'), explicit when-not-to-use (once a specific error has appeared, use misakanet_search), and additional routing detail ('Local stdio server only — the hosted endpoint exposes misakanet_search and misakanet_get_lesson'). It even instructs the agent on the empty-result case: retry with raw error text or submit an intake rather than reading it as a tool failure.

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 side effects ('none'), auth ('none'), rate limits ('local stdio process only'), error cases ('missing intent'), and the output format ('JSON with risk level, matched lessons, and guards'). This is comprehensive behavioral disclosure beyond what annotations typically 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 information-dense yet concise, with the primary purpose front-loaded and separate clauses for inputs, output, errors, side effects, auth, and rate limits. Every sentence earns its place, and the structure is logical and 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?

For a tool with 2 parameters and no output schema, the description is remarkably complete: it covers purpose, usage, parameter roles, expected output, error conditions, side effects, authentication, and rate limits. There is nothing an agent needs to know to call it correctly that 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 description coverage is 100% with both parameters documented. The description adds minimal value by restating that intent is required and context is optional, but the schema already provides examples. It does not elaborate on semantics beyond the schema, so it stays at the baseline for high 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 ('Check risk level') and resource ('before executing high-risk operations'), and clearly distinguishes its function (matches intent against lesson triggers) from the sibling tools which are search, retrieval, and submission operations. It leaves no ambiguity about what the tool does.

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 lists when to use the tool: 'before RAG builds, WSL/GPU tasks, bulk imports, or any operation that might fail.' This provides concrete context and implies it is not needed for safe operations, giving clear guidance without needing to mention alternatives explicitly.

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 excels: it discloses side effects (persists registration record), auth (none), rate limits (one per session), error cases (invalid_client_id), and output structure. It also clarifies the idempotent behavior of client_id, making all behavioral traits explicit.

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

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

The description is structured with clear labels (Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits) and front-loads the core purpose. Every sentence contributes necessary information without redundancy. Despite its length, it is efficiently organized and easily 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?

For a registration tool with optional parameters, multiple access modes, and no output schema, the description covers all required aspects: purpose, usage conditions, parameter semantics, output format, error handling, side effects, auth, and rate limits. Nothing an agent needs to call it 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?

Although schema coverage is 100%, the description adds substantial value beyond the schema: it explains that client_id is optional but ensures the same node_id/token are returned and renewed on subsequent calls, versus minting a new node without it. It also confirms the default for agent_type. This is exactly the kind of semantic enrichment that helps an agent decide how to fill 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: 'Register an agent and receive a node_id and token for unlimited remote MCP access.' It clearly states the tool's purpose and distinguishes it from siblings (only registration tool) by explaining when it's needed (remote write access) versus local stdio or read-only operations.

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

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

Provides explicit when-to-use and when-not-to-use guidance: reading needs no registration, local stdio is unlimited, remote HTTP MCP requires calling this first and then passing the token as the user parameter. Also explains the client_id reuse behavior and its effect on token renewal, leaving no ambiguity about invocation conditions.

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

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

With no annotations, the description carries 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 provided, the description carries full behavioral disclosure. It states side effects ('currently returns a local placeholder report only'), error cases ('missing lesson_id'), auth ('none'), rate limits ('local stdio process only'), and output shape ('JSON with lesson_id, tool, outcome, and status'). It also flags the tool as '[Experimental]', giving the agent an honest expectation of reliability.

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, then organized into labeled sections: Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits. Every sentence earns its place by disclosing a distinct behavioral or invocation detail. The structure makes it easy for an agent to parse.

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 annotations and no output schema, the description is remarkably complete. It covers when to call the tool, required parameters, parameter semantics, expected response, failure mode, side effects, authentication requirements, and rate limits. For a 3-parameter experimental tool, nothing an agent needs to invoke or interpret the result 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 by clarifying the intent of the 'tool' param ('tool names the calling client') and giving concrete outcome examples ('solved, partial, not-helpful, or another short status'). It also documents the expected output fields, which the schema does not. However, it repeats the 'lesson_id is required' schema constraint rather than adding new meaning.

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: 'Record that a public lesson helped with a problem.' This clearly identifies the action and object. It does not explicitly name a sibling, but the phrase 'submit usage feedback' meaningfully differs from the sibling list's read/search/write tools, so the purpose is distinguishable 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 provides explicit usage context: 'Use only after the user or calling agent explicitly chooses to submit usage feedback for a specific lesson.' This tells the agent exactly when the tool is appropriate. It does not mention when not to use it or point to alternatives, 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?

Despite no annotations, the description explicitly states 'Error cases: none. Side effects: none. Auth: none. Rate limits: none.' This fully discloses behavioral traits, leaving no ambiguity.

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 paragraph but well-structured with purpose, input semantics, output schema, and edge cases. It is concise without unnecessary words, though could be more 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?

Given no output schema, the description lists all output fields (user, free_reads_used, etc.) and covers error, side effects, auth, rate limits. Fully complete for this tool.

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

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

Schema coverage is 100% with one parameter. The description adds value by explaining the default value and providing example identifiers (e.g., 'anon:iphash', 'token:xxx'), going beyond the schema.

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

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

The description clearly states 'Check current usage status and remaining quota' using a specific verb and resource. It distinguishes itself from siblings like misakanet_submit_usage, misakanet_search, and 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?

The description gives a clear use case: 'Use to see how many free lesson reads remain and how many credits are available.' It mentions optional user parameter with default, providing context for when to use it.

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.