misakanet

by io.github.Ikalus1988

misakanet_search

Read-onlyIdempotent

[RETRIEVAL / READ] Search MisakaNet's public failure-lesson index by error text, keyword, or topic. This is the primary read path — run it first when you hit an error, before deciding to submit anything. Choosing among the retrieval tools: an actual error or keyword in hand → this one; something risky about to run and no error yet → misakanet_preflight (the third, misakanet_memory_context, is stdio-only and covers the before-you-start case). For a known lesson ID or path, prefer misakanet_get_lesson — it skips ranking and returns the full content. detail controls progressive disclosure: compact (default, ~80 tok/lesson) for broad scans, summary (~200 tok) adds domain/tags/fix, full returns complete lesson data. FAQ: results may also include answered questions (type="faq", issue_url + answer) — if a maintainer already answered the same question, the answer surfaces here. Returns: object {results: [compact: {id, title, problem, freshness, evidence_level, score} | summary: + {domain, tags, fix} | full: the record], source, detail, query}; score is the ranker's relevance for that result and is omitted on the unranked fallback path. On no match: {no_match: true, suggestion, intake}. When the answer is degraded — no index loaded, or the live store refused the read and the corpus came from the snapshot — the response also carries degraded: true, degraded_reasons and a one-sentence notice; read it before concluding that no lesson exists. Example: misakanet_search(query='pip install timeout', domain='python', top=3)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "misakanet_search"
  }
}

Input Schema

Name	Required	Description
`top`	No	Maximum ranked results to return. Defaults to 5; keep small for MCP context and latency.
`kind`	No	Filter by kind: 'lessons' (lesson files only), 'evidence' (results with evidence_refs or verification), 'related' (cross-referenced/tag-overlap), 'all' (default). Auto-detected from query intent when omitted.
`query`	Yes	Required redacted error message, keyword, or topic (e.g. 'pip install timeout' or 'DCO sign-off failed').
`detail`	No	Progressive disclosure: compact (default, ~80 tok) includes id/title/problem/freshness/score; summary (~200 tok) adds domain/tags/fix; full returns complete lesson data with path.
`domain`	No	Optional domain filter such as devops, python, network, feishu, rag, fanuc, or mcp.
`bm25_weight`	No	Override BM25 keyword weight (0-1). Higher favors exact keyword match. Default: 0.65. All weights must sum to 1.0.
`baseline_weight`	No	Override baseline score weight (0-1). Higher favors proven/popular lessons. Default: 0.15.
`metadata_weight`	No	Override metadata bonus weight (0-1). Higher favors matching domain/tags. Default: 0.20.

Output Schema

Name	Required	Description	Default
`query`	No
`detail`	No
`intake`	No
`source`	No
`results`	No
`no_match`	No
`suggestion`	No
`filtered_by_kind`	No
`matched_before_filter`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that `score` is omitted on the unranked fallback path, that FAQ-type records may appear with an answer, and that `degraded`/`degraded_reasons`/`notice` signal a snapshot or refused-read fallback. That degradation warning is exactly the caveat an agent needs before concluding no lesson exists.

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

Conciseness4/5

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

Front-loaded with the retrieval/read framing and the routing rule before any detail. It is dense rather than padded, but the detail-level token costs and the Returns block partially duplicate structured fields, and the FAQ paragraph is a late addition that interrupts flow.

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

Completeness5/5

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

An 8-parameter tool with an output schema and full annotation coverage gets the remaining gaps closed: routing, no-match shape, degraded mode, and progressive-disclosure tradeoffs are all covered. Nothing an agent needs in order to call this correctly is missing, and the explicit example seals it.

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

Parameters3/5

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

Schema coverage is 100% and every parameter already carries a description, so the schema does the heavy lifting. The description's `detail` explanation (token costs per level) largely restates the schema's own detail description, and the example only illustrates query/domain/top. Baseline 3 is appropriate.

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

Purpose5/5

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 by error text, keyword, or topic") and explicitly frames itself as the primary read path. It names the sibling tools it is not (misakanet_preflight, misakanet_memory_context, misakanet_get_lesson), so an agent can disambiguate 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.

Usage Guidelines5/5

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

Gives an explicit decision rule keyed to agent state: error or keyword in hand → this tool; risky action with no error yet → misakanet_preflight; known lesson ID or path → misakanet_get_lesson because it skips ranking. Both the conditions and the alternatives are spelled out, not implied.

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

All misakanet tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.