WOTT

View saved version →

---

name: notebook-management
description: Manage notebooks in wott by finding, reviewing, creating, and updating notebooks. Use when the user wants to work with wott notebooks or needs notebook information and context for a task.
metadata:
  short-description: Manage wott notebooks and build context
  
---

# Notebook Management

Use the wott MCP server to help the authenticated user find, understand, create, and update notebooks.

Notebooks contain the user's knowledge and can provide context for research, projects, and other tasks.

## Quick start

1. Identify what the user wants to do with a notebook.
2. For notebook-specific workflows, consult the relevant guide in `reference/`.
3. Find the relevant notebook using the available notebook listing or search capabilities.
4. Retrieve notebook details or content with `get_notebook` when needed.
5. Create or update notebooks using the appropriate MCP tool.
6. Use relevant notebook information to build context for the user's task.
7. Confirm the MCP operation succeeded before reporting a change.

## Tool-call guardrails

* Always use the authenticated wott user.
* Never ask the user for a Firebase UID, OAuth access token, Firebase credentials, Firestore credentials, or internal server secrets.
* Never fabricate notebook IDs.
* Never fabricate notebook content or project relationships.
* Do not access another user's notebooks.
* Do not perform a write operation when the target notebook or requested change is ambiguous.
* For updates, modify only the fields requested by the user.
* Do not claim a notebook was created or updated unless the MCP tool confirms success.
* If a write operation fails, report the failure accurately.
* Do not blindly retry a failed write operation when it could create a duplicate or unintended change.
* Use the tool schemas exposed by the wott MCP server as the source of truth for available arguments and fields.

## Workflow

### 1. Find or identify a notebook

Use the available notebook search or listing capability when the user refers to a notebook by:

* Name
* Topic
* Keyword
* Description
* Project

For detailed notebook identification and search workflows, read:

`reference/notebook-workflows.md`

Examples of requests that should trigger this workflow:

* "Find my robotics notebook."
* "Show me my research notebooks."
* "Find my notebooks about humanoid robotics."
* "Which notebooks are in my Robotics project?"

If exactly one notebook clearly matches, continue.

If multiple notebooks could match, ask the user to clarify.

If no relevant notebook is found, tell the user.

### 2. Read a notebook

Use `get_notebook` when the user wants information, details, or content from a specific notebook.

If the user provides a notebook ID, use it directly.

If the user provides only a notebook name or description, resolve the notebook first.

For detailed read and resolution workflows, read:

`reference/notebook-workflows.md`

For the available tool arguments and expected notebook output, read:

`reference/notebook-tool-reference.md`

### 3. Create a notebook

Use `create_notebook` when the user clearly asks for a new notebook.

Before creating:

1. Determine the notebook name.
2. Determine any project relationship specified by the user.
3. Determine other required fields from the MCP tool schema.
4. Check for an obvious duplicate when appropriate.
5. Resolve the project when necessary.
6. Create the notebook.
7. Verify the returned result.

For the detailed creation workflow, read:

`reference/notebook-workflows.md`

For the tool schema and output details, read:

`reference/notebook-tool-reference.md`

See:

`examples/create-notebook.md`

for a concrete creation workflow.

Do not create a notebook merely because the user discusses a topic.

### 4. Update a notebook

Use `update_notebook` when the user asks to modify an existing notebook.

Before updating:

1. Identify the target notebook.
2. Resolve it if necessary.
3. Determine exactly what the user wants changed.
4. Update only the requested fields.
5. Preserve unrelated notebook information.
6. Verify the result.
7. Report the change.

For detailed update behavior, read:

`reference/notebook-workflows.md`

For the tool schema, read:

`reference/notebook-tool-reference.md`

See:

`examples/update-notebook.md`

for a concrete example.

If multiple notebooks match, ask the user to clarify before making a change.

### 5. Build context from notebooks

Use wott notebooks as a knowledge source when the user's task depends on information stored in their notebooks.

For example:

> What do my notes say about humanoid robotics?

Follow this general workflow:

```text
identify topic
      ↓
search relevant notebooks
      ↓
select relevant notebooks
      ↓
get_notebook
      ↓
extract relevant information
      ↓
build context
      ↓
answer user
```

For detailed context-building workflows, read:

`reference/notebook-workflows.md`

For a concrete example, read:

`examples/find-notebook.md`

Do not summarize unrelated notebook content.

Do not invent information that is not present in wott.

### 6. Build context across multiple notebooks

When one notebook is insufficient, search for additional relevant notebooks.

```text
user's task
     ↓
search topic
     ↓
relevant notebooks
     ↓
retrieve relevant content
     ↓
combine information
     ↓
build task-specific context
```

Use only information relevant to the user's request.

When multiple notebooks contain overlapping information, avoid unnecessary repetition.

When notebooks contain conflicting information, preserve the distinction rather than silently choosing one.

For detailed workflows, read:

`reference/notebook-workflows.md`

### 7. Project-aware notebook workflows

When the user specifies a project:

> Find the notebooks about locomotion in my Robotics project.

Preserve the project context throughout the workflow.

```text
identify project
      ↓
find notebooks in project
      ↓
search/filter for topic
      ↓
retrieve relevant notebooks
      ↓
build context
```

Do not assume a notebook belongs to a project unless wott or the user establishes the relationship.

For project-aware workflows, read:

`reference/notebook-workflows.md`

When resolving the project itself is necessary, use the `project-management` skill.

## Notebook identification rules

When the user provides a notebook name:

1. Search or list notebooks.
2. Compare the returned results with the user's request.
3. If exactly one notebook is an obvious match, use it.
4. If multiple notebooks match, ask the user to clarify.
5. If no notebook matches, tell the user.

When the user provides a notebook ID, use it directly when the tool accepts it.

Never fabricate notebook IDs.

## Notebook creation rules

Create a notebook only when the user clearly requests creation.

Examples:

* "Create a notebook called Robotics Research."
* "Create a notebook for this research."
* "Create a notebook in my Robotics project."

Before creating, check for an obvious duplicate when appropriate.

If the user specifies a project, preserve that relationship.

If the project is ambiguous and the relationship is required, ask the user to clarify.

For detailed creation behavior, read:

`examples/create-notebook.md`

## Notebook update rules

Only modify information the user requested.

For example:

> Rename my robotics notebook to Humanoid Manipulation.

Only change the notebook name.

Do not overwrite its content, description, project relationship, or other fields unless the user explicitly requests those changes.

For detailed update behavior, read:

`examples/update-notebook.md`

## Context-building rules

When the user asks wott to help answer a question using their existing knowledge:

1. Identify the topic.
2. Search relevant notebooks.
3. Retrieve relevant notebook content when necessary.
4. Extract information relevant to the current task.
5. Build a concise context from that information.
6. Use the context to answer the user's request.

Prefer relevant information over exhaustive retrieval.

Do not present information as coming from wott when it was inferred independently.

For detailed context workflows, read:

`reference/notebook-workflows.md`

For examples, read:

`examples/find-notebook.md`

## Authentication

All notebook operations must use the authenticated wott user.

The model must never request or expose:

* Firebase UID
* OAuth access token
* Firebase credentials
* Firestore credentials
* Internal server secrets

Never attempt to access another user's notebooks.

## Errors

If a notebook cannot be found, tell the user clearly.

If multiple notebooks match, ask the user to clarify.

If a project relationship is ambiguous and affects the requested operation, ask for clarification.

If wott returns an authorization error, do not attempt to bypass it.

If an MCP operation fails, report the failure accurately.

Never claim success unless the MCP tool confirms it.

## References and examples

The `reference/` directory contains detailed notebook-management guidance that should be consulted when the task requires more specific workflow or tool information.

* `reference/notebook-workflows.md` — detailed workflows for finding, reading, creating, updating, resolving ambiguous notebook references, handling project relationships, and building context from one or more notebooks.
* `reference/notebook-tool-reference.md` — wott notebook MCP tools, tool annotations, proposed input schemas, output schemas, structured output, and notebook data representation.

The `examples/` directory contains concrete examples of common notebook-management workflows.

* `examples/create-notebook.md` — creating a notebook, checking duplicates, and preserving project context.
* `examples/update-notebook.md` — identifying and safely updating an existing notebook.
* `examples/find-notebook.md` — finding notebooks, resolving ambiguous results, retrieving notebook content, and building context.

Read the relevant reference or example file when it provides guidance needed for the current task. Do not load unrelated reference files unnecessarily.

Referenced files: 16

View saved version →

---

name: project-management
description: Manage projects in wott by finding, reviewing, creating, and updating projects. Use when the user wants to work with wott projects or needs project information as context for a task.
metadata:
  short-description: Manage wott projects and project context

---

# Project Management

Use the wott MCP server to help the authenticated user find, understand, create, and update projects.

Projects represent larger areas of work and may contain related notebooks and knowledge.

## Quick start

1. Identify what the user wants to do with a project.
2. For project-specific workflows, consult the relevant guide in `reference/`.
3. Find the relevant project using `search_project` or `get_projects`.
4. Retrieve project details with `get_project` when the task requires project-specific information.
5. Create or update projects using the appropriate MCP tool.
6. Use project information as context when it is relevant to the user's broader task.
7. Confirm the MCP operation succeeded before reporting a change.

## Tool-call guardrails

* Always use the authenticated wott user.
* Never ask the user for a Firebase UID, OAuth access token, Firebase credentials, Firestore credentials, or internal server secrets.
* Never fabricate project IDs.
* Do not access another user's projects.
* Do not perform a write operation when the target project or requested change is ambiguous.
* For updates, modify only the fields requested by the user.
* Do not claim a project was created or updated unless the MCP tool confirms success.
* If a write operation fails, report the failure accurately.
* Do not blindly retry a failed write operation when it could create a duplicate or unintended change.
* Use the tool schemas exposed by the wott MCP server as the source of truth for available arguments and fields.

## Workflow

### 1. Find or identify a project

Use `search_project` when the user refers to a project by:

* Name
* Topic
* Keyword
* Description

Use `get_projects` when the user wants to browse or see their projects.

For detailed project lookup and disambiguation rules, read:

`reference/project-workflows.md`

In particular, use the project identification workflow when the user says things such as:

* "Find my robotics project."
* "Open my AI project."
* "Which project is about humanoid robotics?"
* "Show me my projects."

If exactly one project clearly matches, continue.

If multiple projects could match, ask the user to clarify.

If no project matches, clearly tell the user.

Do not guess when selecting a project for a write operation.

### 2. Read a project

Use `get_project` when the user wants details or information from a specific project.

If the user provides a project ID, use it directly.

If the user provides only a name or description, resolve the project first.

For the detailed read workflow, consult:

`reference/project-workflows.md`

For available tool arguments and expected project data, consult:

`reference/project-tool-reference.md`

### 3. Create a project

Use `create_project` when the user clearly asks for a new project.

Before creating a project:

1. Determine the project name.
2. Determine any other required fields from the MCP tool schema.
3. Check for an obvious duplicate when appropriate.
4. Ask for missing required information when it cannot be safely inferred.
5. Create the project.
6. Verify the returned result.

For the complete creation workflow, read:

`reference/project-workflows.md`

For the tool's input and output details, read:

`reference/project-tool-reference.md`

See:

`examples/create-project.md`

for a concrete example of the expected workflow.

Do not create a project merely because the user discusses an idea.

### 4. Update a project

Use `update_project` when the user asks to modify an existing project.

Before updating:

1. Identify the target project.
2. Resolve the project if necessary.
3. Determine exactly which fields the user wants changed.
4. Update only those fields.
5. Verify the result.
6. Report the change.

For detailed update and ambiguity handling, read:

`reference/project-workflows.md`

For the current tool schema, read:

`reference/project-tool-reference.md`

See:

`examples/update-project.md`

for a concrete update workflow.

Never overwrite unrelated project information.

### 5. Build project context

Use project information as context when the user's task depends on an wott project.

For example:

> Help me continue working on my robotics project.

Follow this general workflow:

```text
identify project
      ↓
search_project
      ↓
get_project
      ↓
use project information as context
      ↓
continue with user's task
```

For more detailed context-building workflows, consult:

`reference/project-workflows.md`

When the task also requires notebook information, use the `notebook-management` skill and preserve the project context.

### 6. Project and notebook context

Projects and notebooks may be related.

When the user asks for information across a project and its notebooks:

1. Identify the project.
2. Retrieve the project when necessary.
3. Find relevant notebooks.
4. Retrieve relevant notebook information.
5. Combine the relevant information into context.

Do not assume a notebook belongs to a project unless the relationship is established by the user or wott.

For detailed project workflows and tool behavior, read:

`reference/project-workflows.md`

For notebook-specific workflows, use the `notebook-management` skill.

## Project identification rules

When a user gives a project name:

1. Search for the project.
2. Compare the returned results with the user's request.
3. If exactly one project is an obvious match, use it.
4. If multiple projects match, ask the user to clarify.
5. If no project matches, tell the user.

When the user provides a project ID, do not search unnecessarily. Use the provided ID directly when the tool accepts it.

Never fabricate IDs.

## Project creation rules

Create a project only when the user clearly requests creation.

Examples:

* "Create a project called Robotics."
* "Start a project for my robotics research."
* "Create a new project for this idea."

Before creation, check for an obvious duplicate when appropriate.

If a matching project already exists, avoid creating an unnecessary duplicate. Ask the user whether they want to use the existing project or create a separate one when the distinction matters.

For detailed creation behavior, read:

`examples/create-project.md`

## Project update rules

Only modify information the user requested.

For example, if the user says:

> Rename my robotics project to Physical AI Research.

Only change the project name.

Do not replace the description or other project fields unless requested.

For detailed update behavior, read:

`examples/update-project.md`

## Search and discovery

Use `search_project` when the user is trying to locate a project by topic, name, keyword, or description.

Use `get_projects` when the user wants to browse their projects.

For search and project-resolution examples, read:

`examples/find-project.md`

For the complete search workflow, read:

`reference/project-workflows.md`

## Authentication

All project operations must use the authenticated wott user.

The model must never request or expose:

* Firebase UID
* OAuth access token
* Firebase credentials
* Firestore credentials
* Internal server secrets

Never attempt to access another user's projects.

## Errors

If a project cannot be found, tell the user clearly.

If multiple projects match a potentially destructive or modifying request, ask the user to clarify.

If wott returns an authorization error, do not attempt to bypass it.

If an MCP operation fails, report the failure accurately.

Never claim success unless the tool result confirms it.

## References and examples

The `reference/` directory contains detailed project-management guidance that should be consulted when the task requires more specific workflow or tool information.

* `reference/project-workflows.md` — detailed workflows for finding, reading, creating, updating, resolving ambiguous project references, and building project context.
* `reference/project-tool-reference.md` — wott project MCP tools, tool annotations, proposed input schemas, output schemas, structured output, and project data representation.

The `examples/` directory contains concrete examples of common project-management workflows.

* `examples/create-project.md` — creating a new wott project and handling duplicates or missing information.
* `examples/update-project.md` — identifying and safely updating an existing project.
* `examples/find-project.md` — finding projects, resolving ambiguous matches, and using project results to build context.

Read the relevant reference or example file when it provides guidance needed for the current task. Do not load unrelated reference files unnecessarily.

Referenced files: 14

View saved version →

---
name: search-project
description: Search notebooks within an wott project to find relevant project information and knowledge. Use when the user wants to find information inside a specific wott project.
metadata:
  short-description: Search notebooks in wott projects
---

# Search Project

Search project knowledge using the `search_project` MCP tool.

This skill helps users find relevant information across their project notebooks without modifying project or notebook data.

---

## When to use this skill

Use this skill when the user wants to:

* Find information in a project
* Search project notebooks
* Find notes about a topic
* Find a notebook containing specific information
* Locate previous research or documentation
* Find project context from existing notebook content
* Search for a technical term, person, technology, decision, or concept within a project
* Find relevant notebooks before performing another notebook operation

Typical requests include:

* "Search my AI project for humanoid robotics."
* "Find notes about PostgreSQL in this project."
* "Where did I write about deployment?"
* "Search the project for information about the MCP server."
* "Find notebooks discussing robotics simulation."

---

# Core behavior

The search skill should:

1. Identify the relevant project.
2. Obtain the actual `project_id` when it is not already known.
3. Use `search_project` to search the project.
4. Interpret the returned ranked results.
5. Present the most relevant results clearly.
6. Retrieve a specific notebook with `get_notebook` when the user needs its full content.
7. Never modify project or notebook data during a search-only request.

---

# Available MCP tool

The primary tool for this skill is:

```text
search_project
```

It performs hybrid search over project notebook knowledge.

The search combines:

* BM25
* TF-IDF
* index-based retrieval
* weighted reciprocal rank fusion
* notebook block-to-document resolution
* notebook result enrichment

The current implementation searches notebook knowledge.

It does not currently provide file-source search.

---

# Project identification

`search_project` requires:

```text
project_id
```

The model must use an actual project ID.

Never invent a project ID.

If the user provides a project ID, use it directly.

If the user provides only a project name, use the available project-management capability to identify the project before searching.

If multiple projects are plausible matches, ask the user to clarify.

Example:

```text
User:
Search my AI Research project for humanoid robotics.

Model:
1. Find the "AI Research" project.
2. Get its project_id.
3. Call search_project with that project_id.
```

Do not assume that a project name is its ID.

---

# Search query construction

Use the user's actual information need as the search query.

Good search queries preserve important terms.

For example:

```text
humanoid robotics simulation
```

is better than:

```text
information
```

For a technical request:

```text
MCP OAuth Cloud Run deployment
```

is better than:

```text
deployment stuff
```

Do not unnecessarily rewrite a precise technical query into generic terms.

The search engine performs its own tokenization, normalization, stop-word filtering, and retrieval.

---

# Search limits

The `limit` parameter controls the maximum number of notebook results returned.

Default:

```text
20
```

Maximum:

```text
50
```

Use the default unless the user requests a different number or a larger result set is useful.

For a simple question, a small number of highly relevant results is usually preferable.

For exploratory requests, a larger limit can be useful.

---

# Understanding search results

The search response has this general structure:

```json
{
  "success": true,
  "result_count": 2,
  "items": [
    {
      "markdown_item_id": "notebook_123",
      "block_ids": [
        "block_1",
        "block_2"
      ],
      "score": 0.12,
      "rank": 1,
      "sources": [
        "bm25",
        "tfidf",
        "index"
      ],
      "item": {}
    }
  ],
  "timestamp": "2026-09-03T10:00:00.000Z"
}
```

Important fields:

### `markdown_item_id`

The ID of the notebook item that matched the search.

Use this ID with `get_notebook` when the user needs the actual notebook.

### `block_ids`

The blocks that contributed to the result.

These are internal retrieval references.

Do not normally expose them to the user unless they are useful for debugging.

### `score`

The fused relevance score.

Higher scores indicate stronger ranking within the returned search results.

Do not present the score as a percentage or confidence value.

### `rank`

The final search result ranking.

Rank `1` is the highest-ranked result.

### `sources`

The retrieval methods that contributed to the result.

Possible values:

```text
bm25
tfidf
index
```

These are retrieval mechanisms, not document sources.

### `item`

The enriched notebook information.

Use the notebook metadata to help explain why a result is relevant.

---

# Search versus notebook retrieval

Use `search_project` to discover relevant notebooks.

Use `get_notebook` to retrieve a specific notebook or its full Markdown content.

Typical workflow:

```text
User request
    ↓
Identify project
    ↓
search_project
    ↓
Relevant notebook results
    ↓
Select notebook
    ↓
get_notebook
    ↓
Full Markdown content
```

Do not use search as a replacement for reading the complete notebook when the user explicitly asks to read or summarize a notebook.

---

# Search-only requests

If the user only asks:

> "Find notes about robotics."

Search the project and return relevant notebook results.

Do not automatically modify or create anything.

If useful, offer to open or summarize the most relevant notebook.

---

# Search followed by another operation

Search can be used to discover a notebook before another operation.

For example:

```text
User:
Find my deployment notebook and update it with this new information.
```

The workflow is:

```text
search_project
    ↓
identify notebook
    ↓
get_notebook if needed
    ↓
update_notebook
```

Do not update a notebook until the target is sufficiently identified.

---

# Ambiguous results

If several notebooks are similarly relevant and the user's request requires a mutation, do not guess.

For example:

```text
Deployment.md
Deployment Guide.md
Production Deployment.md
```

If the user says:

> "Update the deployment notebook."

Search first.

If multiple results remain plausible, ask which notebook they mean.

For a read-only search request, multiple relevant results can simply be returned as a ranked list.

---

# Empty results

If `search_project` returns:

```json
{
  "result_count": 0,
  "items": []
}
```

Do not claim that the information does not exist anywhere in the project.

Instead explain that no matching notebook results were found for the query.

Useful next steps include:

* trying different search terms
* searching a related concept
* checking a specific notebook
* checking another project

---

# Security and authorization

Search is always performed for the authenticated MCP user.

The model must never provide:

```text
user_id
```

to `search_project`.

The authenticated user identity is supplied by the MCP server.

The service layer performs project access validation before searching.

The model must never:

* search an arbitrary project without authorization
* request OAuth tokens
* expose authentication information
* expose Firebase credentials
* expose server secrets
* bypass project access controls

---

# Current search scope

The current implementation supports:

```text
Project
└── Notebook knowledge
    ├── notebook blocks
    ├── BM25 retrieval
    ├── TF-IDF retrieval
    └── index retrieval
```

The current MCP contract should not claim that file search is supported.

File search can be added later when file indexing and source resolution are implemented.

---

# Tool selection rules

Use:

```text
search_project
```

when the user wants semantic or keyword discovery across project knowledge.

Use:

```text
get_projects
```

when the project is unknown and must be identified.

Use:

```text
get_notebook
```

when the user wants to retrieve a specific notebook, its content, search notebook filesystem items, or inspect a notebook after discovery.

Use:

```text
create_notebook
```

only when the user explicitly wants a new notebook or folder.

Use:

```text
update_notebook
```

only when the user explicitly wants existing notebook data changed.

Use:

```text
delete_notebook
```

only when the user explicitly wants an existing notebook item deleted.

---

# Response guidelines

Search responses should be concise and useful.

Prefer:

```text
I found 3 relevant notebooks:

1. Humanoid Robotics.md
   Most relevant result. Contains notes on locomotion simulation.

2. Robotics Simulation.md
   Contains simulation experiments.

3. Robotics Research.md
   Contains broader robotics research.

I can open the first one if you want.
```

Do not expose internal retrieval details unless useful.

Do not describe the BM25, TF-IDF, or index score as model confidence.

---

# Reference documentation

For detailed tool behavior, read:

```text
reference/search-tool-reference.md
```

For common workflows, read:

```text
reference/search-workflows.md
```

Examples are available in:

```text
examples/
```

Use the reference documentation when the user's request requires detailed search behavior or a multi-step workflow.

Referenced files: 13