Tools reference

How the tools fit together

The tools follow the four steps of the Katman method: research, plan, build, verify. Your agent doesn’t need to remember the order: katman_start always returns the next call.

Every tool accepts project_root, the absolute path of your site’s project. If you leave it out, Katman uses KATMAN_PROJECT_ROOT, then the root your MCP client reports, then the current folder. Tools return Markdown for the agent, plus structured data where useful. Read-only tools are marked readOnlyHint, tools that use the network openWorldHint, and no tool is destructive. Parameter names below match the current build; your client shows each tool’s live schema.

Audit Week and Pro

Every tool except katman_account needs KATMAN_KEY, which comes with Audit Week or Katman Pro (pricing):

• Audit Week costs $3, paid once, for 7 days. It doesn’t renew, and each account can buy it once. It unlocks the ten audit and recommendation tools: it finds what’s wrong and tells you what to do.
• Katman Pro costs $29/month at the founding price for the first 100 customers (later $49/month), or $290/year. It unlocks every tool: building pages and writing files is Pro.

Without a valid key, a tool explains how to get Audit Week or Pro instead of running, and a Pro-only tool called with an Audit Week key explains that it needs Pro. katman_account needs no key and shows your plan. How to add the key is in Getting started.

Method tools

katman_start

The entry point. Reads .katman/, shows the status of the four steps and returns the next step as an exact tool call. It also adds a one-line plan status.

• Plan: Audit Week and Pro.
• Inputs: site_url (optional; saved to config.json).
• Writes: config.json when you pass site_url.

{ "site_url": "https://your-site.com" }

katman_research

Creates or updates your research: brand, the four-part sentence, the not-X note, 10–12 situations without your brand name, competitors with source and check date, proof with a source, keywords, and the question set (12 unbranded + 2 diagnostic). It rejects situations that contain your brand, competitors without a URL and check date, and proof without a source, and marks every gap as [FILL].

• Plan: Audit Week and Pro.
• Inputs: mode (template, update or show); data (fields to merge, in update mode); generate_questions: true builds the 12 + 2 questions from templates.
• Writes: research.json and research.md.

{ "mode": "update", "generate_questions": true }

katman_account

Shows your plan (Audit Week with the days left, Pro, or none), the features your key unlocks, the masked email of the account, when the key was last checked, and how to connect or upgrade. It’s the one tool that runs without a key. Call it after adding or changing a key.

• Plan: No key needed.
• Inputs: none beyond project_root.
• Writes: nothing. Contacts katman.pro only when KATMAN_KEY is set.

{}

katman_plan

Builds the page plan and the task list in the book’s 30-day order from your research, scan, audit and latest run. Each task has an id, a prompt code (P0–P14), file hints, an acceptance criterion and the tool that verifies it.

• Plan: Audit Week and Pro.
• Inputs: none beyond project_root.
• Writes: plan.json and plan.md; ticked tasks stay ticked when you regenerate.

{}

katman_prompt

Returns one of the 15 prompts, P0–P14, filled with your research data, together with its acceptance criterion, the reason for it, and how Katman verifies it. It adds notes for your framework, such as prerendering options for a Vite single-page app.

• Plan: Pro.
• Inputs: id (P0–P14); situation_id (for P6); lang (en or tr).
• Writes: nothing.

{ "id": "P6", "situation_id": "s1" }

katman_page_brief

A filled page brief: URL, title (situation first, about 60 characters), first sentence, action, proof, who it’s not for, alternatives, FAQ, related pages, the 11-block page anatomy, the JSON-LD to include, and where the file goes in your framework.

• Plan: Pro.
• Inputs: type (situation, comparison, pricing, faq, about, single-question, glossary, tool or home); situation_id; topic; lang.
• Writes: nothing.

{ "type": "situation", "situation_id": "s1" }

katman_generate

Generates files from your research, which stays the single source of truth: robots.txt, llms.txt, Organization, WebSite and SoftwareApplication JSON-LD (with your not-X line in disambiguatingDescription), FAQPage and BreadcrumbList JSON-LD, an analytics snippet that applies the human filter and the ChatGPT channel rule, a server-side bot counter for your platform (Cloudflare Worker, Next.js middleware, Express, Astro or SvelteKit), and an IndexNow key file.

• Plan: Pro.
• Inputs: artifact (for example robots.txt, llms.txt, organization-jsonld, analytics-channel-snippet, bot-counter-snippet); options; write (default false); overwrite (default false).
• Writes: nothing by default: it returns the content and the target path. With write: true it writes that file, and it never replaces an existing file unless you also pass overwrite: true.

{ "artifact": "llms.txt", "write": true }

katman_lint_content

Checks a page against the content rules and the P6, P7 and P8 acceptance criteria: the first 1–3 sentences answer on their own, the one sentence matches your research and llms.txt, no hype words, no unsourced numbers, no placeholders, an update date, 5–8 FAQs, a not-for section, alternatives, at least 3 internal links, and title and description lengths.

• Plan: Audit Week and Pro.
• Inputs: one of file, url or text; page_type (for example situation or comparison).
• Writes: nothing.

{ "url": "https://your-site.com/your-situation-page", "page_type": "situation" }

katman_report

Summarises research completeness, the latest audit’s gate pass rates, visibility changes since the last run, the competitors and domains assistants cite most, plan progress, the top 10 open issues and the next 7 days.

• Plan: Audit Week and Pro.
• Writes: report.md.

{}

Crawl tools

katman_scan_code

A deterministic scan of your codebase: framework and version, builder signatures (Lovable, Bolt, v0, Replit), a rendering verdict (server, static, hybrid or browser-only) with evidence, hosting and preview-URL patterns, public versus app routes, where head tags come from, robots, sitemap, llms.txt, 404 page, JSON-LD, hreflang, onClick navigation, images without alt or size, and whether analytics counts AI visitors.

• Plan: Audit Week and Pro.
• Writes: scan.json.

{}

katman_audit_site

Audits the live site the way AI crawlers see it: robots.txt (AI bot rules, bare prefixes, Cloudflare’s managed block), sitemaps, redirects, HSTS, compression, soft 404s, llms.txt, AI bot access through your CDN or firewall, and for each page its status, noindex, title, description, canonical, headings, words visible without JavaScript, first paragraph, JSON-LD, Open Graph, language, hreflang, images and internal links. Pass urls for a quick check of specific pages after a deploy.

• Plan: Audit Week and Pro.
• Inputs: site_url (your site) or urls (quick verify mode); max_urls (50 by default); include_bot_test; preview_urls.
• Writes: audits/<time>.json and audit.md.

{ "urls": ["https://your-site.com/pricing", "https://your-site.com/faq"] }

katman_indexnow

Sets up and verifies your IndexNow key file, submits only new or changed URLs, and returns the manual checklist for Google Search Console, Bing Webmaster Tools and Brave’s submit form.

• Plan: Pro.
• Inputs: dry_run (default true: shows what would be sent).
• Writes: indexnow.json; contacts api.indexnow.org only with dry_run: false.

{ "dry_run": false }

katman_keywords

Expands a seed phrase through Google’s autocomplete (the seed plus a–z and 0–9, at most 40 throttled requests), groups the results and suggests single-question and situation pages.

• Plan: Audit Week and Pro.
• Inputs: seed; lang; country; save.
• Writes: nothing, unless you save the keywords to your research.

{ "seed": "invoice template for freelancers" }

Visibility tools

katman_visibility_run

Asks your question set to ChatGPT, Claude, Gemini, Perplexity and Grok through OpenRouter, with live web search and your own key, and records for each answer whether you were named, recommended first or cited, and who else was named. It always starts as a dry run that prints the calls and the estimated cost: about $2.4 per run on the default economy panel (range $1.2–3.7), paid by you to OpenRouter. Details: Visibility runs.

• Plan: Audit Week and Pro (plus your own OpenRouter key).
• Inputs: dry_run (default true); models (economy by default, full, probe, family names or OpenRouter slugs); question_ids; samples (1–5 repeats per question); max_cost_usd (default 3); judge; follow_up_sources; temperature; concurrency; allow_google_grounding.
• Writes: runs/<time>.json and measurements.md.

{ "dry_run": true, "models": "probe" }

katman_manual_check

No API cost and within the apps’ terms: you ask a consumer app yourself, logged out with web search on, and paste the answer. Without answer_text it returns the instructions and the exact questions.

• Plan: Audit Week and Pro.
• Inputs: assistant (chatgpt, claude, gemini, perplexity, copilot, grok, google-ai-mode or other); question_id or question; answer_text; sources; logged_in (default false); web_search (default true).
• Writes: a manual run in runs/ and an updated measurements.md.

{ "assistant": "chatgpt", "question_id": "q1", "answer_text": "…pasted answer…" }

katman_setup_monitoring

Generates a GitHub Actions workflow that re-runs the visibility check, and optionally the audit, on a schedule with your OPENROUTER_API_KEY and KATMAN_KEY repository secrets, commits .katman/ changes and opens an issue when your mention rate drops. It makes no network calls itself.

• Plan: Pro.
• Inputs: schedule (cron in UTC; default 0 6 * * 1, Mondays; the book’s 14-day rhythm is 0 6 1,15 * *); include_audit; models; max_cost_usd; write; overwrite.
• Writes: .github/workflows/katman.yml, only with write: true.

{ "schedule": "0 6 1,15 * *", "models": "economy", "write": true }

katman_sync

Sends a summary of your project to your katman.pro dashboard: gate pass counts, visibility rates by assistant and language, plan progress, the top 10 issue titles, dates and the Katman version. It never sends code, file contents, answers, questions or prompts. By default it’s a dry run that shows the exact JSON it would send.

• Plan: Pro.
• Inputs: dry_run (default true).
• Writes: nothing locally; contacts katman.pro only with dry_run: false.

{ "dry_run": true }

Prompts and resources

MCP prompts, shown as slash commands in many clients: katman-start, katman-audit (P1: a report, no code changes), katman-situation-page (takes a situation) and katman-measure.

Resources your agent can read: katman://method, katman://checklist/prepublish, katman://checklist/site-audit, katman://content-rules, katman://prompts/{id} and katman://research.

What each tool may read, write and send is listed on Permissions.