hints.mdx

title	Hints
description	Write usage hints for MCP servers, approve the hints that the model proposes, and know why the safety rules exist.

Hints

Each MCP server has its own result formats, required arguments and limits. A hint tells the model about them, so that its next program is correct the first time. The model sees the hints of a server at two times:

• In the result of search_tools, for the servers that the search finds.
• In the result of run_code, for the servers whose calls failed.

Write a hint

1. Make the folder ~/.claude/code-mode/hints/ if it does not exist.
2. Make one file for each server, for example gmail.md.
3. Write the front matter and one bullet for each fact.
4. Approve the file in the band above the prompt. See Files that you write or change.

---
servers: [Gmail]
identify: [search_threads]
---
- search_threads takes a Gmail search query in `query`, for example "from:me newer_than:7d".

The hint applies in the next call of search_tools or run_code after you approve it. You do not have to start a new session.

To find the tool names for identify, ask the model to run search_tools for the server.

Front matter

Field	Required	What it does
servers	servers or identify	Finds the server by its name.
identify	servers or identify	Finds the server by a tool that it has.
tools	No	Limits the hint to some tools of the server.

* is a wildcard in all three fields.

servers matches the server name that /mcp shows, or the <server> part of mcp__<server>__<tool>. Case and punctuation do not count. A name with no * also matches the end of a name. Thus Datadog matches claude.ai Datadog, claude_ai_Datadog and plugin:engineering:datadog.

Always use identify. In the desktop app, a claude.ai connector has a UUID name, for example mcp__fcef2cd1-…__getJiraIssue. servers cannot find it, but a server with the tool getJiraIssue is Jira in every session. Use a tool name that only this server has.

A hint file with no servers, identify or tools applies to no server. The debug log (claude --debug) names each of these files.

A list can also be JSON, for example servers: ["Data, Dog"]. Use JSON when a name contains a comma.

Where hints come from

Source	Folder	Loads
Bundled	hints/ in the plugin	When hints/sha256.json in the plugin has the hash of the file as it is now
Your own	~/.claude/code-mode/hints/	When you approved the file as it is now
The project	<project>/.claude/code-mode/hints/	When the option projectHints is on, and you approved the file as it is now

The plugin bundles hints for Datadog and Jira. Each hint that the model sees shows the path of its file. Thus you can find and correct a bad hint.

Approve hints that the model proposes

When the model learns something about a server, it can propose a hint with add_hint. A proposal is one file in a pending/ folder, and it has no effect.

The plugin asks the model for a proposal when a run works after earlier tries failed in the same session. A failed try is a failed call to the same server, a failed program or a search_tools query that found no tool. The hint then helps the next session do the task correctly at the first try.

The plugin also asks when a run calls a tool that an earlier run called too, and no hint covers its server. The earlier run was often a probe of the arguments or the result format. The plugin asks once for each server in a session.

While proposals wait, a band above the prompt shows "● 2 proposals for code mode: 1 hint, 1 function" and a Review button. The band also counts the files that are not approved, for example "1 file not approved".

1. Click Review. The band shows one proposal at a time. Click Previous and Next to see the others.
2. Read the hint and the review. Approve only a hint that you can write yourself. If the proposal is taller than the band, scroll the band to read all of it.
3. Click Approve to add the hint to the hint file of the server, or Discard to delete the proposal. These buttons are at the top of the band, above the proposal. If the hint file has the same hint already, Approve does not add it again. If the proposal changes after the band shows it, Approve and Discard fail: review it again.
4. The band shows the result, for example "✓ Hint approved", or the error if the step failed. Click Show next to see the next proposal. Thus a double click cannot approve the next proposal too.

The band shows the proposals of all sessions, closed and headless (claude -p) sessions too. Where Claude Code draws plugin tool results, the add_hint row also shows the proposal with the same buttons. The desktop app does not draw them, so there only the band shows proposals.

To approve a proposal by hand, move its bullets into the hint file of the server, then approve the changed file in the band. To discard it, delete its file in pending/.

Files that you write or change

The plugin loads a hint file only when you approved its text as it is now. Each Approve keeps the SHA-256 of the text of the file in the plugin store. A file that has no such hash does not load. These files have no hash:

• A file that you write or change in your editor.
• A file that another program or a Bash command writes or changes.
• A file that is older than this rule. After the update to this version, approve your files again.

The band lists each of these files as "Hint file not approved", with all of its text. Click Approve to load the file as it is, or Discard to delete the file. If the file changes after the band shows it, Approve and Discard fail: review the file again. Saved functions follow the same rule.

In Cowork and in cloud sessions

Cowork and the cloud sessions of the web and mobile apps do not show the band. Thus you cannot approve a proposal or a file there. In a cloud session, the files in ~/.claude are also lost when the session ends.

In these apps, the model still proposes the hint. It also shows a text block that starts with "Propose this code-mode hint with add_hint". To approve the hint:

1. Copy the block.
2. Paste it into Claude Code in a terminal or in the desktop app, not in Cowork.
3. Let the model propose the hint again in that session.
4. Review the proposal in the band, then click Approve or Discard.

A removal with remove_hint and a change with edit_hint give a block too. The model finds the hint with search_tools and proposes the removal or the change again. The plugin finds these apps from CLAUDE_CODE_ENTRYPOINT and CLAUDE_CODE_REMOTE, which Claude Code sets.

The review on each card

Each field of the card has a label above its value. The table gives the source of each field, so you know whom to trust:

Field	Source	What it tells you
Hint	The model	The text that the model sees in later sessions.
Only for tools	The model	The tools that the hint applies to. The card shows no such field for a hint that applies to all tools of the server.
Claude's reason	The model	What failed before, or what the model had to find out. Compare it with what you saw in the session.
Checks	The plugin	The warnings (⚠), and the number of runs with a failed call to the server in the session that made the proposal.
File	The plugin	The hint file that gets or loses the hint, the number of hints in it, and where the hint applies.

The card shows tool names and file names as code. It shows the hint and the reason as Markdown.

The plugin shows a warning in these conditions:

• The server is not connected in the session.
• A classifier reads the hint as an instruction, not as a fact about a call. The classifier can be wrong.
• The text contains a link, an email address, or a long id or key.
• The text talks about approval, credentials, or what to tell the person.
• The text names a tool of another server.

The review is advice only. It does not approve or discard a proposal. A warning tells you to read the hint again, but it does not prove that the hint is bad. No warning does not prove that the hint is good. The model writes the why and the hint, and text in a tool result can control both.

The classifier is one request to the small fast model of Claude Code for each proposal. If the request fails, the card cannot show its warning.

When you approve a proposal, the plugin removes the review. The hint file gets only the hint.

A removal proposal shows no warning. Its Checks field shows only the failed calls.

Scope

The model proposes a user hint by default. A project hint goes to the project folder, and only when projectHints is on.

Remove a hint that is wrong

A hint can become wrong, for example when a tool changes its result format. Then the model can propose to remove the hint with remove_hint. The model gives the path of the hint file and the text of the hint.

When the model calls remove_hint, this occurs:

1. The model does not see the hint again in the current session.
2. A removal proposal goes to pending/. Its card in the band has the title "Removal of a usage hint".
3. If you click Approve, the plugin removes the hint from its hint file. If the file has no hint left, the plugin deletes the file.
4. If you click Discard, the hint file does not change. The model sees the hint again in the session.

The plugin does not change a bundled hint file, because each plugin update replaces the plugin folder. It adds the hint to ~/.claude/code-mode/hints/removed.json, and the hint does not load again. To get the hint back, delete its entry from removed.json.

To remove a hint by hand, delete its bullet from the hint file in your editor, then approve the changed file in the band.

Change a hint that is wrong

If a hint is wrong or incomplete, the model can propose a corrected hint with edit_hint. The model gives the path of the hint file, the text of the hint and the new text.

When the model calls edit_hint, this occurs:

1. The model does not see the old hint again in the current session.
2. A change proposal goes to pending/. Its card in the band has the title "Change of a usage hint". The card shows the hint now and the new hint.
3. If you click Approve, the plugin puts the new hint in the place of the old hint in its hint file.
4. If you click Discard, the hint file does not change. The model sees the old hint again in the session.

The plugin checks the new hint as it checks a new hint from add_hint. Thus the card shows the same warnings. See The review on each card.

For a bundled hint, the plugin adds the old hint to ~/.claude/code-mode/hints/removed.json. It writes the new hint to the file of the same name in ~/.claude/code-mode/hints/, for example jira.md. If your file of that name is for other servers or tools, the plugin writes the new hint to jira-changed.md. If that file is also for other servers or tools, it uses jira-changed-2.md, and so on. The card names the file.

To change a hint by hand, edit its bullet in your editor, then approve the changed file in the band.

Safety rules

The model follows hints as it follows a CLAUDE.md file. Thus a person who can write a hint can control what the model does with your MCP tools. These rules make a bad hint less probable:

• Project hints are off by default. A person who can commit to a project can put a hint there. Turn on projectHints only for projects that you trust.
• A proposal has no effect until you approve it. A tool result, for example a Slack message or a Jira issue, can contain text that tells the model to save a hint. Such text cannot make a standing instruction.
• A removal or a change has no effect on a hint file until you approve it. Text in a tool result can make the model hide a hint, but only for the current session.
• Each proposal shows a review. It shows why the model proposed the hint, what the plugin saw, and warnings. See The review on each card.
• A file loads only as you approved it. A hint file that the model, a program or another plugin writes or changes does not load until you approve it in the band. See Files that you write or change. Bash commands are not checked: a file that Bash writes waits in the band.
• The model cannot write hint files with its file tools. A guard in the plugin denies Write, Edit and NotebookEdit on files in the hint folders, so the model gets an error at once. It checks the path as written and in real form: the real path of the nearest folder that exists, through symbolic links, then the rest of the path, in any letter case. A case-insensitive volume, the default on macOS, opens ~/.claude/Code-Mode/hints as the hint folder. The hint folders get the same check, so a link in HOME or in a path to a new folder does not change the result. The guard also covers the plugin folder when Claude Code installed it under ~/.claude/plugins/. A folder that you load with --plugin-dir is your own copy, and the guard does not cover it.
• Each hint shows its source file.

These rules are not a full security boundary. The hashes are in a JSON file in ~/.claude/plugins/store/. A program that can write to ~/.claude can change that file, or the code of the plugin. A bundled hint has no Approve: it loads only when the list hints/sha256.json that ships with the plugin has its hash. Thus a program must change two files in the plugin to add a bundled hint. removed.json has no hash, but it can only hide a hint.

For a stronger rule against the file tools of Claude, add a deny rule to ~/.claude/settings.json:

{ "permissions": { "deny": ["Edit(~/.claude/code-mode/hints/**)"] } }