Website Spec

Search the spec

search

Read-onlyIdempotent

Read-only, deterministic full-text search across every spec page. Ranks pages by weighted keyword matches in title, slug, summary, and body, and returns the top results with status, category, canonical URL, Markdown URL, and matching body excerpts. No side effects and no live-web access — it queries an in-memory snapshot bundled at build time, so it returns in well under a millisecond. Use this for keyword/topic lookups when you do NOT already know the slug. Prefer list_topics when you want the complete, unranked set of pages matching a category/status filter; prefer get_topic when you already know the exact slug.

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": "search"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of ranked results to return. Defaults to 5; clamped to 1–25.
`query`	Yes	Free-text query, matched case-insensitively as substrings (not whole words). Split on whitespace; tokens shorter than 2 characters are ignored, so single-letter terms match nothing. Punctuation other than / _ . - is treated as a separator. Each token is scored against title, slug, summary, and body. Example: `content security policy` or `alt text`.

Output Schema

Name	Required	Description
`count`	Yes	Number of results returned (0 if no match).
`query`	Yes	The query that was run, echoed back.
`results`	Yes	Ranked matches, most relevant first; empty when `count` is 0.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedJun 9, 2026
- addedOutput schema / properties / results / description
```
Added value: +"Ranked matches, most relevant first; empty when `count` is 0."
```
- addedOutput schema / properties / results / items / properties / category / description
```
Added value: +"Top-level category this topic belongs to."
```
- addedOutput schema / properties / results / items / properties / status / description
```
Added value: +"Spec status tier: `required`, `recommended`, `optional`, or `avoid`."
```
- addedOutput schema / properties / results / items / properties / summary / description
```
Added value: +"One-sentence summary of the topic."
```
- addedOutput schema / properties / results / items / properties / title / description
```
Added value: +"Human-readable page title."
```

Changed2 schema fields changedJun 8, 2026

changedInput schema / properties / query / description

Previous value: -"Free-text query. Tokenised on whitespace; each token is matched (substring) against title, slug, summary, and body. Example: `content security policy` or `alt text`."New value: +"Free-text query, matched case-insensitively as substrings (not whole words). Split on whitespace; tokens shorter than 2 characters are ignored, so single-letter terms match nothing. Punctuation other than / _ . - is treated as a separator. Each token is scored against title, slug, summary, and body. Example: `content security policy` or `alt text`."

addedInput schema / properties / query / minLength
```
Added value: +1
```

Changed3 schema fields changedJun 4, 2026

addedInput schema / properties / limit / description

Added value: +"Maximum number of ranked results to return. Defaults to 5; clamped to 1–25."

changedInput schema / properties / query / description

Previous value: -"Free-text query."New value: +"Free-text query. Tokenised on whitespace; each token is matched (substring) against title, slug, summary, and body. Example: `content security policy` or `alt text`."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of results returned (0 if no match).",
+      "type": "integer"
+    },
+    "query": {
+      "description": "The query that was run, echoed back.",
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "properties": {
+          "category": {
+            "enum": [
+              "foundations",
+              "seo",
+              "accessibility",
+              "security",
+              "well-known",
+              "agent-readiness",
+              "performance",
+              "privacy",
+              "resilience",
+              "i18n"
+            ],
+            "type": "string"
+          },
+          "excerpts": {
+            "description": "Up to two body snippets showing the matched terms in context.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "mdUrl": {
+            "description": "URL of the raw Markdown for this page.",
+            "type": "string"
+          },
+          "score": {
+            "description": "Relevance score; higher is a closer match.",
+            "type": "number"
+          },
+          "slug": {
+            "description": "Kebab-case identifier; pass to `get_topic`.",
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "required",
+              "recommended",
+              "optional",
+              "avoid"
+            ],
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "description": "Canonical HTML URL of the spec page.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "slug",
+          "title",
+          "status",
+          "category",
+          "score",
+          "url",
+          "mdUrl",
+          "summary"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "query",
+    "count",
+    "results"
+  ],
+  "type": "object"
+}

First observedJun 3, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint; the description adds that it is deterministic, has no side effects, no live-web access, uses an in-memory snapshot, and returns in under a millisecond. No contradiction with annotations.

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?

Four sentences with clear ordering: purpose, return value, behavioral traits, usage alternatives. No filler; each sentence earns its place. Front-loaded with key information.

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?

Given the tool's complexity (full-text search), full schema coverage, strong annotations, and presence of output schema, the description covers all essential aspects: what it does, how it works, when to use it.

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

Parameters5/5

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

Schema coverage is 100% (both parameters have descriptions). The description enriches this with details on substring matching, tokenization, punctuation handling, and limit clamping, adding significant value over the schema alone.

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 clearly states this is a read-only full-text search tool across spec pages, specifies the fields matched (title, slug, summary, body) and return fields. It distinguishes itself from siblings by naming list_topics and get_topic as alternatives, making its purpose unambiguous.

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?

Provides explicit when-to-use guidance ('keyword/topic lookups when you do NOT already know the slug') and direct comparisons to siblings: prefer list_topics for unfiltered category/status results, get_topic for exact slugs. This is exemplary for tool selection.

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

All Website Spec 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.

Resources

Need Help?