Skip to main content
Troubleshooting · core

Use when

A Penumbra answer, message or Grammar entry tells you to call an MCP tool that is not in your tool list.

Looking for something else?

A call that is refused for a missing permission (card Credential). A call that returned pending (problem A change returned pending). A listed tool that fails or contradicts another tool (card Feedback).

​
Signs

  • An answer says “call <tool>”, and your connection’s tool list has no tool with that name.
  • A Grammar entry names an MCP tool in its Doors table that you do not have.
  • An entry says that the default catalog has no call for the job.

​
Why it happens

A connection gets one catalog. The default catalog is small. The full catalog lists the native tools. A Kit lists the tools that its Kit level and its Shapes select. A tool also appears only when the connection holds the permission that it needs, and that access can change. Penumbra writes its answers for every catalog, so an answer can name a tool that only another catalog lists.

​
What Penumbra does

By itself:
  • Gives a connection one catalog: the default catalog, the full catalog or the tools of one Kit.
  • Lists a tool only when the connection holds the permission that the tool needs, and follows the current access when it lists them.
  • Names a tool in some answers although the connection’s catalog does not list it. For example, the default read text can tell an editor to answer a waiting citation with evidence_review.
You must:
  • Read your tool list before you plan a job around a tool.
  • Use another door for the job, or ask for a different connection.
  • Tell the person when a job needs a connection or a permission that you do not have.
Not handled:
  • The answer does not say which catalog lists the tool.

​
Do

  1. Refresh the tool list of your connection. Tool availability follows the current access, and a new client session starts with the current list.
  2. Find the job in its card. The Doors table names the CLI command, the MCP tool for each catalog, and the SDK call. Use the door that you have.
  3. If the card says that the default catalog has no call for the job, use the CLI or the SDK. If you have neither, tell the person that the job needs the full catalog or a Kit that selects the tool.
  4. If a tool needs a permission that you do not hold, tell the person which role or scope is missing (problem what-can-this-credential-see). Do not call a tool that is not listed.
  5. If the text names a tool that no catalog lists, send a feedback report. Do the same if the Doors table of the card does not match the tool list (card rules feedback.1 and feedback.2). Name the text and the tool.

​
Don’t

  • Don’t call a tool that your list does not show, or invent a call that does the same job.
  • Don’t tell the person that Penumbra cannot do the job. Another door may do it.
  • Don’t send feedback for a permission that is missing. That is a refusal that the person can fix (card rule feedback.1).

​
Check

  • You named the door that does the job: a listed tool, a CLI command or an SDK call.
  • The person knows if the job needs another connection.
Card credential. Card project. Card feedback, with rules feedback.1 and feedback.2. Card approval. Card workspace. Card extraction. Problem what-can-this-credential-see.

​
Keep going

Credential · Project · Feedback · Approval · Workspace · Extraction