Tool Naming Convention

Guidelines for naming and creating new tools in ShotGrid MCP Server

Tool Naming Convention

This document outlines the naming convention for tools in the ShotGrid MCP Server and provides guidelines for creating new tools.

MCP Tool Name Requirements

According to the Model Context Protocol (MCP) specification, tool names must follow these requirements:

• Tool names must match the regular expression pattern: ^[a-zA-Z0-9_-]{1,64}$
• This means tool names:
  • Can only contain letters, numbers, underscores, and hyphens
  • Cannot contain periods, spaces, or other special characters
  • Must be between 1 and 64 characters in length

ShotGrid MCP Server Tool Naming Convention

To maintain consistency and clarity, we follow these naming conventions for tools in the ShotGrid MCP Server:

Prefix-Based Naming

All tools should use a prefix that indicates their category:

Prefix	Description	Example
sg_	Direct ShotGrid API wrappers	sg_find, sg_create
entity_	Entity operations	entity_create, entity_update
note_	Note-related operations	note_create, note_read
playlist_	Playlist-related operations	playlist_create, playlist_find
thumbnail_	Thumbnail-related operations	thumbnail_get_url, thumbnail_download
vendor_	Vendor-related operations	vendor_find_users, vendor_create_playlist
search_	Search-related operations	search_entities, search_by_date
batch_	Batch operations	batch_create, batch_download

Naming Structure

• Use underscores to separate words in tool names
• Use clear, descriptive names that indicate the tool’s purpose
• Follow the pattern: [prefix]_[action]_[optional_qualifier]
• Examples:
  • sg_find - Find entities using ShotGrid API
  • note_create - Create a note
  • playlist_add_versions - Add versions to a playlist
  • thumbnail_download - Download a thumbnail

Creating New Tools

When creating new tools for the ShotGrid MCP Server, follow these guidelines:

1. Choose the Appropriate Module

Place your tool in the appropriate module based on its functionality:

• api_tools.py - Direct ShotGrid API wrappers
• note_tools.py - Note-related tools
• playlist_tools.py - Playlist-related tools
• thumbnail_tools.py - Thumbnail-related tools
• search_tools.py - Search-related tools
• vendor_tools.py - Vendor-related tools
• Create a new module if your tool doesn’t fit into existing categories

2. Define the Tool Function

@server.tool("prefix_action_qualifier")
def tool_function_name(param1: Type1, param2: Type2) -> ReturnType:
    """Tool description.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ToolError: Description of when errors are raised.
    """
    try:
        # Tool implementation
        return result
    except Exception as err:
        handle_error(err, operation="tool_function_name")
        raise  # This is needed to satisfy the type checker

3. Register the Tool

Tools are registered using the @server.tool() decorator. Make sure to:

• Use a name that follows the naming convention
• Provide proper type hints for parameters and return values
• Include comprehensive docstrings
• Implement proper error handling

4. Add Tests

Create tests for your tool in the appropriate test module:

• Test normal operation
• Test error conditions
• Test edge cases

Examples

Basic Tool Example

@server.tool("entity_create")
def create_entity(
    entity_type: EntityType,
    data: Dict[str, Any],
) -> Dict[str, Any]:
    """Create a new entity.

    Args:
        entity_type: Type of entity to create.
        data: Entity data.

    Returns:
        Dict[str, Any]: Created entity data.

    Raises:
        ToolError: If entity creation fails.
    """
    try:
        result = sg.create(entity_type, data)
        return result
    except Exception as err:
        handle_error(err, operation="create_entity")
        raise

Advanced Tool Example

@server.tool("search_entities_with_related")
async def search_entities_with_related(
    entity_type: EntityType,
    filters: List[Dict[str, Any]],
    fields: List[str],
    related_fields: Dict[str, List[str]],
    order: Optional[List[Dict[str, str]]] = None,
    limit: Optional[int] = None,
) -> List[Dict[str, Any]]:
    """Search for entities with related fields.

    Args:
        entity_type: Type of entity to search.
        filters: Search filters.
        fields: Fields to return.
        related_fields: Related fields to return, keyed by field name.
        order: Optional order specification.
        limit: Optional result limit.

    Returns:
        List[Dict[str, Any]]: List of matching entities with related fields.

    Raises:
        ToolError: If search fails.
    """
    try:
        # Implementation details...
        return results
    except Exception as err:
        handle_error(err, operation="search_entities_with_related")
        raise

Conclusion

Following these naming conventions and guidelines ensures that tools in the ShotGrid MCP Server are consistent, clear, and easy to use. It also helps maintain compatibility with the MCP specification and provides a better experience for users of the server.