site-kit

Overview Schema Source Related Servers Discussions Admin

Read the full teaching note for one rule

explain_rule

Read-onlyIdempotent

Look up a review rule by bracketed id to get trigger condition, rationale, better code, sources, and corpus stats. Omit the id to browse the rulebook; filter by tier or search.

Instructions

Given a rule id from a review — the part in square brackets — return the whole note: the exact trigger condition and where that number came from, why it matters, what it is teaching, the better move with its code, every source with its own caveat, and what the rule measured across the corpus the rulebook was built from.

Call it with no id to list the rulebook. Pass a tier, a category, or a search term to narrow it.

Input Schema

TableJSON Schema

Name	Required	Description
`rule`	No	A rule id, for example "T2-EDGE-STRIPE". Leave it out to list the rulebook.
`tier`	No	List one tier: 1, 2, 3, "floor", "honesty", "structure", "craft", "trap" or "ledger".
`search`	No	List rules whose title or description contains this text.

Output Schema

TableJSON Schema

Name	Required	Description
`fix`	No
`why`	No
`rule`	No
`tool`	Yes	Which tool produced this.
`rules`	No
`status`	Yes	pass = checked and clean. fail = checked and found problems. skipped = nothing was measured. error = the tool could not run.
`problem`	No
`headline`	Yes	One sentence verdict, safe to show a non-technical user.
`rulebook`	No
`error_code`	No	Set only when status is "error".

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.0.0Sep 17, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already establish read-only and idempotent behavior; the description adds useful behavioral context by explaining that omitting the id lists the rulebook and that filters narrow results. It does not mention pagination or freshness behavior, but the output schema and read-only annotation cover the main safety profile.

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

Conciseness5/5

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

The description is two short paragraphs with the main action front-loaded. The enumerated note contents are long but each item adds meaning, and there is no filler or restatement of the title.

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

Completeness4/5

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

For a read-only tool with no required parameters and an output schema, the description covers the main lookup mode, the list mode, and possible filters. The only real gap is the unresolved 'category' filter mention, and it could clarify how to choose among the optional arguments, but these are minor.

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 description coverage is 100%, so the schema already documents the rule, tier, and search parameters. The description adds a useful 'part in square brackets' cue, but much of the no-id/list behavior is already present in the schema. The mention of 'category' as a possible filter does not match a schema property, so the description does not substantially exceed schema semantics.

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?

The description opens with a concrete verb and resource: given a rule id, return the whole teaching note, and it enumerates what the note contains. It also clearly distinguishes the no-id rulebook-listing mode, so an agent can tell this lookup from the check/review sibling tools.

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

Usage Guidelines4/5

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

The description gives explicit invocation contexts: with a rule id from a review, with no id to list the rulebook, and with tier/search/narrowing filters. It does not explicitly name alternatives or exclusions, but the rule-id-from-review cue and unique resource make when-to-use clear.

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

Deploy Server