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

Beyond the annotations, it discloses input precedence, traversal validation, canonical-set matching behavior, output truncation to 5000 characters, error cases, no side effects, no auth, and local stdio operation. These details materially help an agent call the tool correctly and interpret failures.

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 organized into input, output, error, side-effect, auth, and rate-limit notes. Despite its length, every section carries actionable information for a lookup tool with nuanced path/id behavior.

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?

There is no output schema, so the description appropriately explains the {path, content} return shape and the 5000-character truncation. It also covers errors, precedence, path validation, and safety context, leaving no material gap for an agent invoking 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?

Although schema coverage is already 100%, the description adds important semantics: provide exactly one of path or id, path takes precedence when both are supplied, and id matches only the canonical lesson set while mirrors and translations require explicit paths. This goes well beyond the 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 explicitly distinguishes this lookup tool from misakanet_search, so an agent can choose it without opening either 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 gives explicit usage conditions: use after misakanet_search returns a promising result or when a lesson is explicitly referenced. It also states the exclusion clearly: do not use it for broad discovery.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantial context: no auth, rate limiting, no local fallback, error cases including missing_lesson_reference and hosted_endpoint_unavailable, and no side effects. It also explains why an empty events list would be a wrong proxy-failure answer, which is valuable 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 the read-only evidence purpose and then proceeds through inputs, return shape, errors, side effects, auth, and limits. It is mostly well structured, though it repeats read-only/no-auth/rate-limit information and is 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?

With no output schema, the description compensates by giving the return object shape, evidence levels, note field, error cases, auth status, rate limits, and side effects. It gives an agent enough to call the tool and interpret both success and failure 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 lesson_id and lesson_path. The description adds meaning beyond the schema by explaining that either identifier is acceptable, that the endpoint derives the lesson id from lesson_path the same way, and that supplying neither is refused before any network call.

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: returns evidence of a lesson being reused, specifically E4 observed reuse. It sharply distinguishes E4 from E3 hints such as citations, votes, and provenance lines, so an agent can identify the tool's unique role without opening other 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?

Explains when to use it: to check whether a lesson is proven by real usage rather than self-reported evidence. It also says what does not count as E4, but it does not explicitly route among nearby sibling tools such as get_lesson or usage_status.

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?

Beyond the readOnly/idempotent annotations it discloses a genuinely non-obvious trait: an intake still in the local queue is answered from there (delivery=local_queue) because the hosted endpoint has never seen it. It also documents the error contract ({error, hint} when both identifiers are missing), plus auth and rate-limit status, which the annotations do not cover.

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?

Opens with purpose, then the usage trigger, then labeled sections for input semantics, output shape, edge cases, side effects, auth and rate limits — front-loaded and scannable. It runs long for a 2-parameter read call, and the labeled list format is slightly heavier than the content requires.

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?

There is no output schema, so the description carries the return-shape burden and does: events[], count, status, poll_hint, plus the event types (answered, converted, accepted, lesson_published). Combined with the error case and side-effect profile, an agent has everything needed to call and interpret 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%, but the description adds the crucial constraint the schema omits: required is empty in the schema, yet the description states "provide intake_id ... or dedup_key ... At least one is required." That single sentence prevents a zero-argument call that the schema alone would permit, and it explains both identifiers originate from submit_intake.

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?

"Check your agent inbox for answered questions and conversion receipts" names a specific verb and resource and makes the tool's scope unmistakable. It is clearly distinct from misakanet_submit_intake (write side) and misakanet_me_events (event log), so an agent can route between siblings without inspecting 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?

"Use after submitting an intake (misakanet_submit_intake) to poll for maintainer answers or lesson conversions" gives an explicit prerequisite and a polling context. It stops short of stating when NOT to use it (e.g. versus misakanet_me_events or misakanet_search), so it is strong but not complete routing 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?

Goes well past the annotations: it discloses silent clamping at 10, 200-char per-field truncation, the BM25-to-plain-scorer degradation when the index is absent, zero-rows-without-error for an unknown domain, and that corpus freshness is bounded by the local checkout. Auth, rate limits and side effects are stated explicitly, and the 'local stdio only' note explains why the hosted endpoint differs. Minor tension: 'does not touch the network' reads as closed-world against openWorldHint=true, but this is a scope clarification rather than a contradiction of intent.

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 correctly (pair positioning first, then per-parameter semantics, then output, errors, side effects), and every section is doing work. It is long — the trailing Auth/Rate-limits/Side-effects lines partly re-cover what readOnlyHint and openWorldHint already imply — but the density justifies most of the length for a tool with this many silent-failure modes.

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, and the description compensates in full by naming the return keys ({task, lesson_count, lessons, context_block}) and interpreting lesson_count 0 as 'no match yet' rather than a tool failure — exactly the failure mode an agent would otherwise misread. Error cases and degradation behavior are also enumerated.

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 a fourth by sharpening *why* the task string must be concrete ('intent-only phrasing retrieves nothing') and by giving a counter-intuitive diagnostic that the schema omits: an empty result with a domain set is 'usually the filter, not an empty corpus.' It largely restates the schema's clamping and vocabulary rules, so it does not reach 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 and positions itself against a named sibling: it is the 'proactive half of the pair' to be called before a task, versus misakanet_search after an error appears. The framing ('proactive' vs. reactive) lets an agent pick between them without opening either 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?

Explicit temporal routing rule: call this BEFORE starting a task, and only call misakanet_search 'once a specific error has actually appeared.' It adds a second conditional ('leave [domain] out unless you know the domain') and names the remediation path on an empty result (retry with raw error text or submit an intake).

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?

Goes well beyond the annotations by disclosing output structure, the keyword-overlap matching mechanism, the index_status/index_error caveat that changes how empty matched_lessons must be read, error behavior for missing intent, and explicit 'no side effects / no auth / local stdio only' statements. The only mild tension is openWorldHint=true versus 'local stdio process only', but this does not contradict the readOnly/destructive/idempotent declarations.

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 dense output-semantics block, and every sentence carries information the agent needs. The output-explanation section is long, but it is justified because no output schema exists; a light trim would still be possible.

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 output schema, the description supplies the full return shape, the interpretation rule for empty matched_lessons, the degraded index_status case, guards semantics, and error behavior. An agent has everything needed to call it and to read the result 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 both parameters; the description adds the required/optional distinction and richer worked examples ('build RAG pipeline with ChromaDB', 'WSL, GPU 8GB'). It stops short of saying how keyword overlap is computed, which would fully close the loop on intent phrasing.

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 explains the mechanism (matching intent against lesson triggers and risk profiles). It is clearly distinguishable from siblings like misakanet_search or misakanet_get_lesson, which retrieve lessons rather than assess pre-execution risk.

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 frames it as a proactive pre-flight step. The trigger list plus the 'before you start' timing gives an agent actionable selection criteria with no inference 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?

Adds substantial context beyond annotations: error case (invalid_client_id), side effect (persists registration record in usage_meter), auth (none), rate limits (one per session), and the conditional reuse behavior. The reuse semantics (same node/token when client_id supplied) nuance the idempotentHint=false annotation but do not contradict it, since the no-client_id default still mints a new node.

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 organized and front-loaded with purpose and access rules. It is on the long side and the SECURITY paragraph is somewhat repetitive of the earlier client_id sentence, keeping it just below top marks.

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 no output schema, the description specifies the return shape ({node_id, token, registered_at, agent_type, reused?}) and covers error cases, side effects, auth, and rate limits. Nothing an agent needs to invoke 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?

Schema coverage is already 100%, but the description goes further than the schema: it frames client_id as 'a key, not a label,' warns that knowing someone's client_id is enough to obtain their token, and instructs generating a random UUID rather than deriving from hostname. This is meaningful semantic value beyond the field 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?

States a specific verb ('Register an agent') and concrete outcome ('receive a node_id and token for unlimited remote MCP access'). It also immediately scopes what does NOT need registration (reads, local stdio), distinguishing it from the sibling write/read tools.

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

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

Explicit when-to-use rules: 'Reading needs no registration; only write tools do,' local stdio is unlimited, and for remote HTTP MCP 'call this tool first to get a token.' No alternative or exclusion 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?

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds real context beyond that: side effects none, auth none, local stdio rate constraint, enumerated error cases, and what explain/staleness do to results. It stops short of describing ranking order or result freshness semantics in depth, so not a 5.

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 parameters, then output/errors/side effects — a sensible order. It is somewhat long and the parameter paragraph duplicates schema text, costing a point on economy.

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 10 parameters, no output schema, and a stateful index, the description covers what results look like (results[] and source, ranked lesson summaries), error behavior, auth, side effects, and rate limits. Everything an agent needs to call this correctly is present.

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's 'Input semantics' paragraph largely restates the schema descriptions for query, domain, top, kind, explain, and detail rather than adding new meaning; the one extra nuance is the omitted-kind auto-detection examples, which the schema also covers.

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 ('Search MisakaNet's public failure-lesson index') plus the accepted query forms (error text, keyword, topic). It also distinguishes itself from misakanet_get_lesson, which is named as the tool for full content.

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 ('when you need to discover relevant lessons and do not already know a lesson ID') and when not to ('Do not use for private log collection; search only with redacted snippets'). It names the alternative (misakanet_get_lesson) and the condition that selects 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?

Beyond the annotations it discloses concrete side effects (the intake becomes a GitHub issue on MisakaNet), an offline degradation path (local queue only, surfaced as delivery=local_queue in the receipt), the duplicate-submission error, and that there are no auth requirements but the hosted endpoint's rate limits apply. Destructive/read-only hints are consistent with a non-idempotent write that files a report; the openWorldHint=false is arguably loose given the GitHub-issue side effect, but it is not a direct contradiction of anything stated.

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 trigger before moving into labeled sections (Input semantics, Output schema, Error cases, Side effects, Auth, Rate limits), so an agent can stop reading early. It is dense but nearly every clause carries decision-relevant information; only the output-field enumeration runs slightly long given no output schema exists.

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 write tool with no output schema, the description supplies the return shape, the failure modes, the fallback delivery behavior, auth, and rate-limit context — everything needed to call it and interpret the result 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 would be 3, but the description adds real value by stating problem is required, that kind defaults to missing_lesson, and which fields are optional as a group. It does not restate the enum semantics or the source parameter, leaving some reference work to 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 first sentence states a specific verb (submit) and resource (failure-case intake) plus the exact triggering condition (no matching lesson, or a stale/incorrect one), which cleanly separates it from siblings like misakanet_search and misakanet_write_lesson. An agent can identify the tool's job 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?

It names the alternative explicitly ("Use after misakanet_search fails to find a good match") and gives the second qualifying condition (a problem resolved but not yet documented). It also enumerates the intake kinds via context, so the agent knows which classification applies rather than guessing.

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?

Goes well past annotations: discloses that only a local placeholder report is produced while remote submission can be disabled via MISAKANET_USAGE_DISABLE_REMOTE, states auth is none, scopes rate limits to a local stdio process, and enumerates the error case (missing lesson_id). These are exactly the side-effect and environment facts an agent cannot get from readOnlyHint/destructiveHint alone.

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 the purpose, then sequences the prerequisite, input semantics, output shape, errors, side effects, auth, and limits in labeled clauses. Dense but nearly every clause carries new information; the '[Experimental]' tag and repeated output-field listing are the only near-redundancy.

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

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

No output schema exists, yet the description supplies the return JSON keys, the single failure mode, the placeholder-vs-remote side effect, and the auth/rate-limit posture. For a 3-parameter tool this leaves no material 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 coverage is 100%, so the schema already documents all three parameters. The description restates the same value examples for outcome and the same role for tool without adding syntax, constraints, or defaults beyond them, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Record that a public lesson helped with a problem') and scopes it to post-hoc reporting, which separates it from misakanet_search, misakanet_get_lesson, and misakanet_write_lesson. The 'AFTER a lesson has been used' framing makes the distinction operational rather than descriptive.

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 specifies the triggering condition ('AFTER a lesson has been used and the outcome is known') and names the sibling to consult first (misakanet_usage_status for remaining quota). The pre-check ordering is stated, not inferred.

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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses error behavior ('returns defaults on failure'), auth requirements (none), and rate limits (none) — all facts the structured fields do not provide. The 'side effects: none' line mildly echoes destructiveHint=false, but the surrounding context is genuinely additive.

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 and sequencing before the labeled reference sections (input/output/errors/side effects), and every block is scannable. Slight redundancy: the 'user' parameter is described in both the prose and the schema, and 'side effects: none' duplicates the annotations.

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, yet the description enumerates the returned fields (free_reads_used, free_reads_limit, free_reads_remaining, credits, is_registered, next), including the 'next' hint that ties into the register/submit workflow. For a single-optional-param read tool, nothing an agent needs 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 above that by explaining the two identifier forms ('anon:iphash' vs 'token:xxx') and where the token comes from (misakanet_register). It repeats the default value already in the schema, so it is not a full 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 current usage status and remaining quota', which an agent can distinguish from misakanet_submit_usage (which consumes quota) and misakanet_register (which upgrades to write access). The description also explicitly names both siblings, so differentiation is 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 gives explicit sequencing ('Use before calling misakanet_submit_usage') and a clear conditional branch ('Call misakanet_register if is_registered is false and you need write access'). Both when-to-use and which-alternative-to-pick are spelled out.

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?

Beyond the annotations (non-read-only, non-idempotent write), the description discloses the auth requirement, the concrete side effect (writes to data/contribution_queue.jsonl), the full error surface including a quality-score threshold of 75 and duplicate submission, and the rate-limit/runtime constraint (local stdio only). This is exactly the kind of post-annotation context the dimension rewards.

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 action and trigger, then packs auth, inputs, outputs, errors, and side effects into labeled clauses — nothing is wasted. It is dense and slightly list-like rather than fully scannable, which keeps it just under the top mark.

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 output schema present, the description compensates by describing the return JSON (lesson_id, status, quality_score, quality_notes, redactions_applied, receipt), and it also covers auth, error cases, and persistence side effects. An agent has everything needed to decide to call it 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 description coverage is 100%, so every one of the 9 parameters is already documented with examples (e.g. 'pip install timeout on corporate proxy', domain enums, 2000-char limit). The description only restates which fields are required vs optional, adding no format or format-syntax detail beyond the schema; baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Submit a complete, structured failure lesson') and defines the exact content required (failure→root cause→fix→verification chain). This clearly separates it from read-oriented siblings like misakanet_search and misakanet_get_lesson, and from the distinct write targets misakanet_submit_usage and misakanet_submit_intake.

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 an explicit trigger condition ('Use after resolving a problem and documenting the full failure→root cause→fix→verification chain'), which is actionable context. It does not name an alternative tool or an explicit when-not-to-use case, so it stops short of the 5 tier.

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