MisakaNet

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: the 5000-char content cap, faithful truncation reporting with a full_content_url escape hatch, path-validation refusal with code=invalid_lesson_path, the argument-precedence rule, and per-code retry semantics. This is the kind of disclosure an agent needs to avoid mis-handling 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?

Front-loads the [RETRIEVAL / READ] tag and the core action, then layers usage, argument rules, and return/error semantics in a logical order with zero filler sentences. It runs long and re-documents return shapes already covered by the output schema, which costs a point, but every sentence carries information.

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 two-param read tool with a published output schema, the description covers everything an agent needs: selection criteria, argument precedence, validation limits, truncation handling, and error-code triage. Nothing material to invoking it correctly is left implicit.

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 meaning the schema does not: the "provide exactly one of id or path, path takes precedence if both are supplied" precedence rule, the neither-supplied error behavior, and the constraint that only lessons/<topic>/<slug>.md files are readable. These resolve genuine ambiguity in the oneOf schema (which oddly permits both).

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 ("Fetch one public MisakaNet lesson by repository path or lesson ID") and immediately differentiates itself from the sibling misakanet_search by naming the handoff relationship. An agent can separate this retrieval tool from search/write siblings without reading 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?

Explicitly says when to use it ("after misakanet_search returns a promising result to pull the full fix content") and encodes the alternative in the error guidance itself ("lesson_not_found — do not retry, search instead"). When-not-to-retry conditions are spelled out per error code, which is unusually actionable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds traits not in them: no auth required, rate-limited, explicit {error} response when neither lesson_id nor lesson_path is given, and the E0/E3/E4 output levels. The return-shape paragraph is partially redundant with the existing output schema, which keeps this from 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 the [READ-ONLY EVIDENCE] tag and the core purpose in the first sentence, and most of the length is load-bearing E4/E3 definition rather than filler. The return-shape sentence duplicates the output schema and the backward-compatibility aside is a minor detour, but overall the structure is disciplined for the amount of semantics it must carry.

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 an output schema present, the description needn't explain return values, and it does cover the genuinely important gaps: the parameter-required error case, no-auth/rate-limit behavior, and the evidence-level semantics that an agent cannot infer from the schema. The remaining unanswered question is how a lesson_id resolves against a lesson_path, which is a small gap for a two-parameter lookup.

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% and both parameters are documented inline, so the baseline is 3. The description adds only the invocation rule already implied by the schema's oneOf ('Provide lesson_id or lesson_path') plus an example; it contributes no format, resolution-order, or precedence detail (e.g. what happens if both are supplied).

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 — return evidence of lesson reuse — and goes further by defining exactly what qualifies as E4 (two or more distinct clients retrieved the lesson) versus E3 hints (citations, votes, provenance lines). It differentiates itself from its own alias ('misakanet_get_my_events') but never explicitly contrasts with siblings like misakanet_get_lesson or misakanet_search, so it stops short of full sibling differentiation.

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 to check whether a lesson is proven by real usage, not just self-reported' gives a clear selection criterion against other evidence-gathering paths. It does not name an explicit alternative tool to call for weaker/sandbox-level evidence, but the E3-vs-E4 boundary effectively tells the agent when this tool applies and when it does not.

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), it discloses rate limiting, no-auth requirement, and the semantic meaning of each status value ('answered' carries the maintainer answer, 'converted' carries the resulting lesson_id). Those are exactly the operational facts an agent needs before calling.

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 and readable, but it declares the return shape twice ('Returns: {status: ...}' followed by 'Returns: object {intake_id, status, ...}') and repeats read-only/no-auth facts. That redundancy is wasted space in an otherwise tight definition.

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 two-parameter lookup tool with a full output schema and annotations, nothing an agent needs is missing: valid identifier forms, an example call, status vocabulary, and the read-only/no-auth posture are all 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 description coverage is 100%, so both parameters are already documented with examples in the schema. The description restates the accepted formats ('issue-1234' or '1234', 16-char hash) without adding syntax or constraints beyond that, so 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?

States a specific verb+resource ('Check the status of a previously submitted intake') and immediately distinguishes the scope from re-submitting. An agent can tell this apart from misakanet_submit_intake 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?

The phrase 'without re-submitting' plus the requirement to pass an ID from a prior submit_intake response clearly establishes when to use this instead of the submit sibling. It does not spell out an explicit 'do not use when...' exclusion, so it stops short of a 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is largely covered; the description's 'no side effects — safe to call multiple times' restates them. Genuine added context is the auth requirement: anonymous calls are refused with JSON-RPC -32000 Unauthorized plus a recovery hint. However, it discloses nothing about cost, latency, or behavior when no lesson matches the intent — a meaningful gap for a guard tool that gates other operations.

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 the bracket tag, then when-to-use, then safety, then auth, then return shape — a logical order. It is slightly padded: the parenthetical aside 'which this sentence exists to keep you from discovering the hard way' is self-referential filler and the Returns line duplicates the 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 two-parameter, output-schema-backed guard tool, the description covers purpose, triggering conditions, idempotency, the authentication prerequisite and its failure mode, and even sketches the return shape. There is essentially nothing an agent needs in order 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 coverage is 100%, including the required-intent description, so the baseline is 3. The description earns an extra point by explaining what intent means functionally — the agent's planned action, matched against lesson triggers — and supplying a concrete example call (intent='build RAG pipeline with ChromaDB') that demonstrates the expected specificity level.

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 gives a specific verb and resource — 'Check risk level' as a preflight gate that 'Matches agent intent against lesson triggers' — and leads with a bracketed tag '[GUARD / RISK CHECK]' that separates it from the storage/search siblings (misakanet_search, misakanet_get_lesson, misakanet_write_lesson). An agent can tell immediately that this is a pre-action safety check rather than a data retrieval tool.

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 trigger contexts ('before RAG builds, WSL/GPU tasks, bulk imports, or any operation that might fail') and explicitly permits repeated calls ('safe to call multiple times before acting'). It also names the prerequisite path — call misakanet_register first and pass the same client_id — which is the alternative-action guidance an agent needs before invoking.

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 only provide hints about side-effect profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial behavioral context beyond that: token lifetime (~30 days), the node/pseudonym model, what happens without client_id (new node each call), and the effect of referral_code (counted only on new node). It also warns about what to keep private and what happens to evidence/history.

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?

Densely informative but all content is functional: onboarding instruction, security warning, return shape, usage example, and referral semantics. It is front-loaded with the core purpose and then builds logically. Every sentence earns its place; no fluff or redundant restatement of the title.

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 an output schema present, the description does not need to list every return field, but it goes further and explains the subtle semantics of reused, token lifetime, renewal, and referral counting. Given the tool has multiple behavioral traps (client_id regeneration, referral double-counting, privacy), the description is complete enough 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 already covers both parameters at 100%, including constraints and purpose for client_id and agent_type. The description adds deeper meaning for client_id (same node/token on later calls, treat as key, don't publish), and layers the referral_code meaning on top. The only small shortfall is that fractional aspect of describing agent_type example values is already in schema, so top scores for schema-heavy descriptions are not needed; 4 reflects the added semantic 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 states a specific verb ('Get a Bearer token') and resource (authenticated access), with an explicit result (`{node_id, token, ...}`). It also differentiates from reading tools (misakanet_search / misakanet_get_lesson) that don't need registration, so the agent can immediately identify this as the onboarding/auth tool and not a content access tool.

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 is explicit about when to use it ('Get a Bearer token for authenticated access'), when not to use it (reading needs no registration), and names alternatives (misakanet_search / misakanet_get_lesson). It also covers renewal behavior, client_id reuse, and optional referral_code semantics, giving the agent complete routing and usage context.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds genuinely non-obvious behavior: the degraded-mode flags (degraded, degraded_reasons, notice) when the index is missing or the live store refused the read, the unranked fallback where `score` is dropped, and the no_match/suggestion/intake shape. That is real value beyond the annotations, though the FAQ aside is narrower in importance.

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 the action guidance and following with the alternative and a worked example, so the important routing information comes first. However, the multi-line 'Returns' enumeration is redundant for a tool that already ships an output schema, which is wasted length.

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?

An output schema and full annotations exist, and the description still supplies the pieces those do not: the degraded-answer path, the no-match path, the FAQ result type, and the ranked-vs-unranked score distinction. Nothing an agent needs to interpret a surprising response 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%, so the baseline is 3. The description's `detail` tiers and token estimates largely restate what the schema already documents (including the compact key list and the weight sum-to-1.0 constraint), so it adds little parameter meaning the agent cannot already read.

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 (Search) plus the exact resource (MisakaNet's public failure-lesson index) and the match dimensions (error text, keyword, topic). It also names the sibling it is not — misakanet_get_lesson — for the known-ID case, so an agent can route 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?

Explicitly declares itself the primary read path and says to run it first on an error before submitting anything, then carves out the alternative: prefer misakanet_get_lesson for a known lesson ID or path because it skips ranking. That is when-to-use, when-not, and the alternative in one place.

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 declare non-read-only, non-destructive, non-idempotent, closed-world, but the description adds behavior the annotations cannot convey: open auth (no Bearer), rate limiting, auto-redaction, dedup_key semantics, poll_hint.recheck_after_seconds timings (21600s questions, 86400s failures), and the GitHub-issue triage pipeline. This is well beyond the structured fields.

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?

Long but densely front-loaded: the primary decision (this tool vs write_lesson) and the question-vs-report routing come first, then polling/return details, then examples. Nearly every sentence carries operational information, though the return-shape enumeration is heavier than strictly needed given an 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 9-parameter, open, asynchronous submission tool, the description covers the key decision points: when to use it, auth posture, what artifact it produces, how duplicates and answers surface, and how to poll. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining the kind enum's routing consequence (question vs lesson, and the server-side auto-detection when kind is omitted) and demonstrating real parameter values in the worked examples.

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 and an explicit scope statement: submit an open, rate-limited intake that produces a GitHub issue rather than a merged lesson. It directly names the sibling it is not (misakanet_write_lesson) and the condition that separates them, so an agent can distinguish 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?

Explicit when-to-use rules: use this when you only have a partial failure description or want to ask a question; use misakanet_write_lesson (Bearer required) once you have structured title/domain/problem/root_cause/fix. It further routes kind='question' vs failure reports and explains the auto-detection fallback and the asynchronous answer/poll workflow.

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

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

The description adds substantial behavioral context beyond the annotations: it requires authentication, routes through lesson-gate/lint/review, persists as a versioned git lesson, and becomes immutable once merged. It also documents the return shape including error format, which is valuable for agent expectations.

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 sentence earns its place: structured labeling, auth requirements, alternative routing, immutability policy, return type, and an example. It is front-loaded with the core purpose and spends no words on 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?

For a tool with 9 parameters, 5 required fields, an output schema, and sibling alternatives, this description is complete. It covers auth, validation pipeline, immutability, correction workflow, return values, and the intended alternative route. Nothing needed 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?

The input schema covers all 9 parameters with descriptions, so the baseline is 3. The description names the five required fields and provides a realistic example call, but does not add deeper meaning to individual parameters beyond what the schema already provides. This is acceptable given the high schema 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 and resource: 'Submit a complete, structured failure lesson ... as a formal submission.' It also distinguishes itself from sibling misakanet_submit_intake, and explains there is intentionally no update/delete sibling because lessons are immutable once merged. This 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?

Usage guidance is explicit: use this for validated, complete submissions requiring a Bearer token, and use misakanet_submit_intake instead for quick open reports with partial failure descriptions. The description also prescribes how corrections should be handled (new intake/PR) rather than using this tool again.

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