shorturl_get_usage_guide

Instructions

Provides detailed information on how to use the ShortURL tools
effectively, including parameters, examples, and best practices.

Returns:
    Complete usage guide for ShortURL tools.

Implementation Reference

• tools/info_tools.py:6-71 (handler)

  The actual handler function for the shorturl_get_usage_guide tool. Decorated with @mcp.tool(), returns a comprehensive markdown usage guide string about all available ShortURL tools, example usage, response structure, and notes.

  @mcp.tool()
  async def shorturl_get_usage_guide() -> str:
      """Get a comprehensive guide for using the ShortURL tools.
  
      Provides detailed information on how to use the ShortURL tools
      effectively, including parameters, examples, and best practices.
  
      Returns:
          Complete usage guide for ShortURL tools.
      """
      # Last updated: 2026-04-05
      return """# ShortURL Tools Usage Guide
  
  ## Available Tools
  
  ### URL Shortening
  **shorturl_create** - Shorten a single URL
  - url: The long URL to shorten (required, must start with http:// or https://)
  
  **shorturl_batch_create** - Shorten multiple URLs at once
  - urls: List of long URLs to shorten (max 10 per batch)
  
  ## Example Usage
  
  ### Shorten a Single URL
  ```
  shorturl_create(url="https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9")
  ```
  
  **Response:**
  ```json
  {
    "success": true,
    "data": {
      "url": "https://surl.id/1uHCs01xa5"
    }
  }
  ```
  
  ### Batch Shorten Multiple URLs
  ```
  shorturl_batch_create(urls=[
      "https://example.com/very-long-url-1",
      "https://example.com/very-long-url-2"
  ])
  ```
  
  ## Response Structure
  
  ### Successful Response
  - **success**: `true` - indicates the request was successful
  - **data.url**: The shortened URL (e.g., `https://surl.id/abc123`)
  
  ### Error Response
  - **success**: `false` - indicates an error occurred
  - **error.code**: Error code (e.g., `api_error`, `bad_request`)
  - **error.message**: Human-readable error description
  - **trace_id**: Request trace ID for debugging
  
  ## Notes
  - The service is **free** (0 credits per request)
  - Short URLs use the `surl.id` domain
  - Short URLs are permanent and redirect to the original URL
  - Only valid HTTP/HTTPS URLs can be shortened
  - Rate limiting applies to prevent abuse
  """

• tools/info_tools.py:6-7 (registration)

  Registration via @mcp.tool() decorator on the async function shorturl_get_usage_guide. The tools/__init__.py imports info_tools which triggers the registration when tools module is loaded in main.py.

  @mcp.tool()
  async def shorturl_get_usage_guide() -> str:

• main.py:118-120 (registration)

  The tool is listed in the server startup banner showing available tools.

  safe_print("    - shorturl_create")
  safe_print("    - shorturl_batch_create")
  safe_print("    - shorturl_get_usage_guide")

• main.py:166-169 (registration)

  The tool is registered in the MCP Server Card (for HTTP transport) listing available tools.

  {
      "name": "shorturl_get_usage_guide",
      "description": "Get API usage guide",
  },