# MCP Tool Annotation Template

## For inclusion in tool descriptions/schemas:

```typescript
// Add this annotation to any Playwright MCP tool description:
const toolDescription = `
Navigate to a URL and interact with web pages.

🤖 COLLABORATION API AVAILABLE:
Models can communicate directly with users through JavaScript functions:

• mcpNotify.info('message') - Send info to user
• mcpNotify.success('completed!') - Show success  
• mcpNotify.warning('be careful') - Display warnings
• mcpNotify.error('something failed') - Show errors
• mcpNotify.loading('processing...') - Persistent status

• await mcpPrompt('Shall I proceed?') - Get user confirmation
• mcpInspector.start('Click the login button', callback) - Interactive element selection

When elements are ambiguous or actions need confirmation, use these functions 
to collaborate with the user for better automation results.

Full API: See MODEL-COLLABORATION-API.md
`;
```

## Short version for tool schemas:

```typescript
const shortAnnotation = `
🤖 MODELS: Use mcpNotify.info('message'), mcpPrompt('question?'), and 
mcpInspector.start('click element', callback) for user collaboration.
`;
```

## For browser_evaluate tool specifically:

```typescript
const evaluateDescription = `
Evaluate JavaScript on the page.

🤖 COLLABORATION FUNCTIONS AVAILABLE:
After running this tool, models can use JavaScript to communicate with users:
- mcpMessage(), mcpNotify.*() for messages  
- mcpPrompt() for confirmations
- mcpInspector.start() for element selection

Example: await page.evaluate(() => mcpNotify.success('Task completed!'));
`;
```

## Implementation Strategy:

1. **Add to existing tool descriptions** - Append the short annotation
2. **Include in documentation** - Reference the full MODEL-COLLABORATION-API.md
3. **Tool-specific notes** - Add context-relevant collaboration hints
4. **Examples in schemas** - Show practical usage patterns

This ensures models discover and use the collaboration features naturally while using the MCP tools.