> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Path Convention

> Naming rules for tool paths and display names.

## Path format

Tool paths are dot-separated lowercase identifiers validated against:

```
^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$
```

* Must have at least two segments (e.g., `github.issues` minimum, typically three)
* Each segment starts with a lowercase letter
* Segments can contain lowercase letters, digits, and underscores
* Segments are separated by dots

### Convention

The recommended pattern is `service.resource.action`:

| Path                   | Service  | Resource | Action |
| ---------------------- | -------- | -------- | ------ |
| `github.issues.list`   | github   | issues   | list   |
| `github.issues.create` | github   | issues   | create |
| `gmail.messages.read`  | gmail    | messages | read   |
| `calendar.events.list` | calendar | events   | list   |

## Display names

Tool names use **Title Case with spaces**:

| Path                   | Name                |
| ---------------------- | ------------------- |
| `github.issues.list`   | List Issues         |
| `github.issues.create` | Create Issue        |
| `github.repos.search`  | Search Repositories |
| `gmail.messages.list`  | List Gmail Messages |
| `slack.messages.post`  | Post Message        |

## Tools proxy mapping

Inside sandbox scripts, the tools proxy translates property chains to dot paths:

```typescript theme={null}
// This call:
await tools.github.issues.list({ owner: "org", repo: "repo" });

// Invokes tool path: "github.issues.list"
```

Calling a namespace (not a leaf tool) throws a helpful error:

```typescript theme={null}
await tools.github.issues();
// Error: "github.issues" is a namespace, not a tool. Use tools.search() to find tools.
```

## Namespace and plugin ID

A tool's path prefix usually matches the plugin ID (`github` plugin -> `github.*` tools). However, multi-service plugins may use service-specific prefixes:

* Plugin ID `google-workspace` uses `gmail.*` and `calendar.*` prefixes
* This is intentional -- tools are namespaced by the service they interact with