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 delivers: read-only with no side effects or local writes, no auth, the hosted endpoint's anonymous read burst rate window, no local fallback as a proxy, and named error cases (missing_lesson_reference, hosted_endpoint_unavailable) plus the warning that an empty events list would be a different, wrong answer. It also discloses the key semantic caveat that only real client retrievals confer E4, which no structured field conveys.

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 a [READ-ONLY EVIDENCE] tag and the core distinction, then organized into Returns/Input/Errors/Side effects/Auth/Rate limits. The E3-vs-E4 exposition is long but earns its place for correct interpretation; there is minor redundancy across the two auth/read-only statements.

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 supplies the return shape (lesson_id, events[{type, count|queries|sources, evidence_level}], evidence, note). Combined with explicit side effects, auth, rate limits, and error taxonomy, nothing an agent needs to call or interpret 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 100%, so baseline would be 3, but the description adds meaning beyond the schema: lesson_id is a filename stem while lesson_path has its id derived from the path 'the same way', and passing neither is refused before any network call — clarifying the oneOf semantics operationally.

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', and immediately scopes it to E4 observed reuse (client retrieval counts) versus E3 hints like citations and votes. It also names its semantic alias (misakanet_get_my_events) and distinguishes scope ('evidence for the lessons your node submitted/used'), so an agent can separate it from get_lesson or search.

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

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

Explicit when-to-use is given: 'Use to check whether a lesson is proven by real usage, not just self-reported', plus the hard precondition that one of lesson_id/lesson_path must be supplied or the call is refused. It never names a sibling tool as the alternative for the adjacent task (e.g., fetching lesson prose), so it is clear context but not full when/when-not 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?

With zero annotations the description carries the full burden and does: it declares read-only, no side effects, no auth, no rate limits, describes the local_queue short-circuit, and documents the error payload. This is exactly the behavioral context annotations would otherwise 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?

Front-loads purpose and usage before the mechanics, and every labeled segment (input semantics, output, errors, side effects) carries information. It is dense and slightly over-packed, but nothing is truly redundant given there is no output schema.

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-annotation, no-output-schema read tool it covers everything an agent needs: input requirement, output event shape, the local_queue edge case, error behavior, and safety/rate-limit profile. Nothing material 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, but the description adds genuinely new meaning: it states at least one of intake_id or dedup_key is required, whereas the schema marks neither as required. It does not say what happens if both are supplied, keeping it below a 5.

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 your agent inbox for answered questions and conversion receipts") and ties it to the submit_intake workflow. It does not explicitly differentiate from the close sibling misakanet_me_events, so an agent must infer the boundary between the two.

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

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

Explicitly says when to use it ("after submitting an intake... to poll for maintainer answers or lesson conversions") and names the predecessor tool. It lacks an explicit when-not or a routing rule against me_events, so it is clear context but not full exclusion guidance.

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

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

With no annotations 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, the description carries full burden and does so thoroughly: it discloses side effects ('none — read-only check'), auth requirements ('none'), rate limits ('local stdio process only'), the exact JSON return structure including the subtle risk_level/matched_lessons interaction, and the failure mode where an unreadable index produces empty matched_lessons for a different reason. This is exceptional behavioral disclosure.

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

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

The description is front-loaded with purpose and usage, then flows into input semantics, output schema, error cases, and operational traits. It is dense but well-organized. It is somewhat long, but every section earns its place given the tool's complexity. Minor deduction for slight redundancy in re-explaining the empty matched_lessons scenario twice.

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?

Complete for a 2-parameter read-only tool with no annotations and no output schema. The description covers purpose, usage, parameters, return structure including edge cases, error handling, side effects, auth, and rate limits. Nothing material is missing for an agent to invoke and interpret results 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 documents both parameters. However, the description adds concrete examples ('build RAG pipeline with ChromaDB', 'WSL, GPU 8GB') and clarifies the semantic distinction between intent (what you plan to do) and context (the environment), which goes beyond the schema's brief descriptions. Baseline 3 is exceeded because the description actively enriches parameter 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?

States a specific verb and resource ('check risk level before executing high-risk operations') and immediately distinguishes the tool from the sibling set: none of misakanet_search, misakanet_get_lesson, or misakanet_memory_context is a preflight risk check. The scope and purpose are unmistakable.

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

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

Explicitly says when to use it ('before RAG builds, WSL/GPU tasks, bulk imports, or any operation that might fail') and clarifies the timing ('before you start'). This is direct when-to-use guidance with no ambiguity about the alternative (i.e., simply proceeding without a preflight check).

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?

With no annotations, the description carries the full burden and does so: it discloses the real side effect (files a GitHub issue on MisakaNet), the degraded offline path (local queue only, signalled by delivery=local_queue in the receipt), auth requirements (none), rate limits, and the two failure modes (missing problem, duplicate submission). This is exactly the operational context an agent needs before a mutating, externally-visible call.

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, and the labelled segments (Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits) make it scannable rather than rambling. It is dense and reads somewhat like a spec dump - enumerating every receipt field is borderline - but no sentence is genuinely idle given there is no output schema.

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 8-parameter mutating tool with no annotations and no output schema, the description supplies the return contract (submitted, intake_id, status, redactions_applied, quality_score, dedup_key, poll_hint, receipt), the error cases, and the offline behaviour. Nothing an agent needs to call it correctly 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 earns more by stating that problem is required, that kind defaults to missing_lesson (a default the schema does not document), and by characterizing the rest as optional. It still does not explain the source parameter or the semantic interplay between kind values and matched_lesson_id beyond the schema's own 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 and resource (submit a failure-case intake) plus the triggering condition (no matching lesson, or stale/incorrect lesson), which is far more precise than the tool name alone suggests. It also implicitly separates itself from the read-side siblings by referencing misakanet_search as the upstream step, so an agent can place it in the workflow 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?

Explicitly says when to call it: after misakanet_search fails to find a good match, or when the user resolved an undocumented problem. It names the alternative (search) but does not state the inverse routing rule - e.g. that a good match plus feedback should go to misakanet_submit_usage rather than here, or when to prefer misakanet_write_lesson over kind=new_lesson_candidate.

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.