# Tool Creation Requirements Checklist
When asked to create a new tool for the Updation MCP system, I MUST gather ALL of the following information before proceeding. No exceptions.
## 1. Tool Identity & Purpose
- [ ] Tool name (snake_case)
- [ ] Tool description (clear, specific)
- [ ] Tool purpose and business value
- [ ] Expected inputs and outputs
- [ ] Is this a new version of an existing tool? (e.g., `list_vendors_v2`)
## 2. Access Control (RBAC)
### Required Role Information
- [ ] Which roles can access this tool?
- [ ] GLOBAL_ADMIN? (full system access)
- [ ] ORG_ADMIN/MANAGER? (organization-wide)
- [ ] PLATFORM_ADMIN/MANAGER? (platform-specific)
- [ ] DEALERSHIP_ADMIN/MANAGER? (dealership-specific)
- [ ] Regular users? (ORG_USER, PLATFORM_USER, etc.)
### Tool Category
- [ ] Which category does this tool belong to?
- [ ] PUBLIC_TOOLS (no auth required)
- [ ] AUTHENTICATED_TOOLS (any logged-in user)
- [ ] ORGANIZATION_TOOLS
- [ ] PLATFORM_TOOLS
- [ ] DEALERSHIP_TOOLS
## 3. Context Policy
### Page Types
- [ ] Which pages can this tool be used on?
- [ ] System pages (dashboard, settings, profile)
- [ ] List/Table pages (vendor_table, contract_table, etc.)
- [ ] Detail pages (vendor_detail, contract_detail, etc.)
- [ ] Create pages (vendor_create, contract_create, etc.)
### Entity Requirements
- [ ] Does this tool require an entity context?
- [ ] Entity type (vendor, contract, invoice, etc.)
- [ ] Is entity ID required?
- [ ] Should entity ID come from page context?
### Operation Type
- [ ] Is this tool read-only or write operation?
- [ ] Read-only (queries, exports, views)
- [ ] Write (create, update, delete)
## 4. Implementation Requirements
### API Integration
- [ ] Which Laravel API endpoints will this tool use?
- [ ] Required request headers?
- [ ] Authentication requirements?
- [ ] Rate limiting considerations?
### Error Handling
- [ ] Expected error scenarios
- [ ] Error response format
- [ ] Retry strategy (if applicable)
### Performance
- [ ] Expected response time
- [ ] Pagination requirements
- [ ] Caching strategy (if needed)
## 5. Tool Policy Definition
I MUST create a `ToolContextPolicy` that specifies:
```python
ToolContextPolicy(
allowed_page_types=Set[PageType], # Which pages?
requires_entity=bool, # Entity required?
entity_type=Optional[EntityType], # Which entity?
read_only=bool # Operation type?
)
```
## 6. Required Code Changes
1. Add tool policy to correct policy dict:
```python
VENDOR_POLICIES = {
"new_tool": ToolContextPolicy(...)
}
```
2. Add tool to correct RBAC category:
```python
class RBAC:
ORGANIZATION_TOOLS = {
"new_tool", # Add here
}
```
3. Create tool implementation with correct decorator:
```python
@registry.register_tool(
name="new_tool",
policy=POLICIES["new_tool"],
description="..."
)
async def new_tool():
pass
```
## Validation Rules
I MUST NOT proceed with tool creation if:
1. Tool name exists in any policy dict
2. Tool lacks clear RBAC assignment
3. Tool lacks ToolContextPolicy
4. Tool's page types don't match its purpose
5. Entity requirements unclear
6. API integration details missing
## Example Gathering Process
```
ME: Before I create the tool, I need several key pieces of information:
1. Tool Basics:
- What should we name this tool?
- What exactly does it do?
- What are the inputs/outputs?
2. Access Control:
- Which user roles should have access?
- Is this for all authenticated users or specific roles?
3. Context Requirements:
- On which pages will this tool be used?
- Does it need an entity (like a specific vendor/contract)?
- Is it read-only or does it modify data?
4. API Details:
- Which backend API will this tool use?
- What authentication/headers needed?
Please provide these details so I can ensure the tool is properly integrated.
```
## Implementation Checklist
Once I have ALL required information, I MUST:
1. [ ] Create tool policy
2. [ ] Add to correct policy dict
3. [ ] Update RBAC categories
4. [ ] Implement tool with proper decorator
5. [ ] Add error handling
6. [ ] Add logging
7. [ ] Document the tool
## Example Valid Tool Request
A complete tool request should look like:
```
Create a tool that:
- Name: list_vendor_contracts
- Purpose: List all contracts for a vendor
- Access: ORG_ADMIN, PLATFORM_ADMIN, DEALERSHIP_ADMIN
- Pages: VENDOR_DETAIL only
- Entity: Requires VENDOR entity
- Operation: Read-only
- API: GET /api/vendors/{id}/contracts
```
## Example Invalid Tool Request
An incomplete tool request (MUST NOT proceed):
```
Create a tool to manage vendors
- Name: manage_vendor
- Purpose: Handle vendor operations
❌ Missing: RBAC roles
❌ Missing: Page types
❌ Missing: Entity requirements
❌ Missing: API details
```
