Skip to main content
Glama
surbhimotghare

MCP-Server

AI Makerspace: MCP Session Repo for Session 13

This project is a demonstration of the MCP (Model Context Protocol) server, which utilizes the Tavily API for web search capabilities. The server is designed to run in a standard input/output (stdio) transport mode.

Related MCP server: Web Search MCP Server

Project Overview

The MCP server is set up to handle web search queries using the Tavily API. It is built with the following key components:

  • TavilyClient: A client for interacting with the Tavily API to perform web searches.

Prerequisites

  • Python 3.13 or higher

  • A valid Tavily API key

⚠️NOTE FOR WINDOWS:⚠️

You'll need to install this on the Windows side of your OS.

This will require getting two CLI tool for Powershell, which you can do as follows:

  • winget install astral-sh.uv

  • winget install --id Git.Git -e --source winget

After you have those CLI tools, please open Cursor into Windows.

Then, you can clone the repository using the following command in your Cursor terminal:

git clone https://AI-Maker-Space/AIE7-MCP-Session.git

After that, you can follow from Step 2. below!

Installation

  1. Clone the repository:

    git clone <repository-url>
    cd <repository-directory>
  2. Configure environment variables: Copy the .env.sample to .env and add your Tavily API key:

    TAVILY_API_KEY=your_api_key_here
  3. πŸ—οΈ Add a new tool to your MCP Server πŸ—οΈ

Create a new tool in the server.py file, that's it!

βœ… Answer:

Added Advanced URL Shortener Tool to MCP Server:

  • Function: shorten_url(url: str, custom_alias: str = "")

  • APIs: Dual service support with automatic fallback

    • Primary: TinyURL's free API service

    • Fallback: V.gd service for custom aliases

  • Features:

    • Auto-adds https:// to URLs without protocol

    • Custom alias support with unique generation

    • Service fallback for optimal reliability

    • Comprehensive error handling for all edge cases

    • User-friendly response formatting with service information

    • Automatic alias uniqueness using timestamp-based generation

  • Testing: Comprehensive test suite with test_final_shortener.py

  • Error Handling: Graceful handling of duplicate aliases, invalid URLs, and service failures

Running the MCP Server

To start the MCP server, you will need to add the following to your MCP Profile in Cursor:

NOTE: To get to your MCP config. you can use the Command Pallete (CMD/CTRL+SHIFT+P) and select "View: Open MCP Settings" and replace the contents with the JSON blob below.

{
    "mcpServers":  {
        "mcp-server": {
            "command" : "uv",
            "args" : ["--directory", "/PATH/TO/REPOSITORY", "run", "server.py"]
        }
    }
}

The server will start and listen for commands via standard input/output.

Usage

The server provides a web_search tool that can be used to search the web for information about a given query. This is achieved by calling the web_search function with the desired query string.

Activities:

There are a few activities for this assignment!

πŸ—οΈ Activity #1:

Choose an API that you enjoy using - and build an MCP server for it!

πŸ—οΈ Activity #2:

Build a simple LangGraph application that interacts with your MCP Server.

You can find details here!

βœ… Answer: Enhanced URL Shortener MCP with Smart LangGraph Application

You can find details in the URL_SHORTENER_README.md!

Available Tools

13 tools
check_url_safetyC

Check if a URL is safe and identify potential security risks

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It does not disclose how safety is determined (e.g., blocklists, scanning), side effects, permissions, or reliability. Vague term 'identify potential security risks' lacks specificity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise, but under-specified. It is not overly long, but the brevity sacrifices necessary detail, making it barely adequate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple parameter and existence of an output schema, the description should clarify how to interpret results and differentiate from validate_url. It fails to provide enough context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It only names the parameter implicitly via the tool's purpose, offering no details on URL format, supported schemes, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks URL safety and identifies security risks, distinguishing it from sibling tools like validate_url which likely focus on format validation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., validate_url, web_search). The description assumes the agent knows context, missing exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_url_collectionC

Create a new URL collection for organizing shortened URLs

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
descriptionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits, but it only states 'Create' without mentioning side effects, permissions, or any other behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence of 8 words, but it could be slightly more informative without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is too minimal for a tool with no annotations and 0% schema coverage; it does not explain the concept of a URL collection or describe the output, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the meaning or usage of the 'name' or 'description' parameters, failing to compensate for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Create' and the resource 'URL collection', and it is specific enough to distinguish from sibling tools like list_collections or shorten_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for its use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

expand_urlC

Expand a shortened URL to see its final destination

ParametersJSON Schema
NameRequiredDescriptionDefault
shortened_urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fails to disclose behavioral traits like redirect following, error handling, or rate limits. It only states the basic outcome.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is concise but under-specifies the tool. It is not overly verbose, but lacks necessary detail, making it barely adequate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description does not mention what happens for invalid URLs or non-shortened inputs. Incomplete for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description adds no meaning beyond the parameter name 'shortened_url', such as format, examples, or validity constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Expand') and the resource ('shortened URL'), and distinguishes it from sibling tools like 'shorten_url' and 'check_url_safety'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives, such as checking URL safety or validating. Lacks explicit context or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_qr_codeC

Generate a QR code for a URL and return it as base64 encoded image

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
sizeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states the output format (base64 image) but does not disclose any side effects, permissions, rate limits, or error handling. For a generation tool, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 12-word sentence that is front-loaded with the action. It is concise and direct, with no filler. However, it could be slightly more structured by separating parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 parameters and an output schema, the description covers the main purpose and output format. However, it omits parameter semantics, which are not explained in the schema either. Given no annotations, it is moderately complete but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'url' or 'size' parameters. It adds no meaning beyond the schema field names. The default for 'size' is not explained, nor is its effect on the QR code.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a QR code for a URL and returns it as a base64 image. The verb 'Generate' and object 'QR code' are specific, and the output format is mentioned. It distinguishes from sibling tools which focus on URL manipulation or validation, not QR generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any constraints or prerequisites. It lacks any 'when to use' or 'when not to use' context, leaving the agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_url_metadataB

Extract metadata from a URL including title, description, and other information

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the action. It fails to disclose behavioral traits such as network access, redirect handling, error behavior, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence of 12 words. It is efficient but could include more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (though unseen), the description covers the basic purpose and output fields. However, it lacks behavioral context and usage guidance, leaving gaps for an agent to infer correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero description coverage for the 'url' parameter. The description does not add any meaning or constraints (e.g., format, length) beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'extract' and resource 'metadata from a URL', and specifies output fields (title, description). This differentiates it from sibling tools like check_url_safety, expand_url, or shorten_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like check_url_safety or expand_url. The description lacks any contextual hints about appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_collectionsB

List all URL collections

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description should disclose behavioral traits. It states 'list all' implying read-only, but does not mention authentication requirements, rate limits, or behavior when no collections exist. This is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (3 words). While it is clear, it could benefit from a slightly more structured phrasing, e.g., 'Lists all URL collections in the system.' Still, it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not detailed), the description need not explain return values. However, it lacks contextual completeness about scope (e.g., user-specific vs global), and the sibling create_url_collection implies collections exist but no further context is provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema coverage (empty schema). No additional parameter semantics are needed, as there is nothing to describe. The baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all URL collections' – a specific verb ('List') and resource ('URL collections'). This distinguishes it from sibling tools like create_url_collection (create) and search_urls (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. For example, does it list all collections globally or only the user's? Are there scenarios where search_urls would be more appropriate? The description lacks such context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_my_urlsB

List saved URLs with optional filtering by collection or tags

ParametersJSON Schema
NameRequiredDescriptionDefault
collectionNo
tagsNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavior like read-only nature, pagination, or default ordering, but it only states the basic function without additional traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core purpose without any unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description doesn't need return details, but it lacks info on default behavior (limit=20) and result format, making it adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to 'collection' and 'tags' as filters, but does not clarify format or the 'limit' parameter, and schema descriptions are absent (0% coverage).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists saved URLs and specifies optional filtering by collection or tags, distinguishing it from siblings like search_urls and list_collections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as search_urls or expand_url, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

roll_diceC

Roll the dice with the given notation

ParametersJSON Schema
NameRequiredDescriptionDefault
notationYes
num_rollsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to mention the format of accepted notation, whether the roll is random, any constraints, error behavior, or the return value. This is a significant transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded, but it is under-specified. Every sentence is technically earned but the content is insufficient. It is concise at the expense of usefulness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite being a simple tool, the description is incomplete for an agent to use it correctly. It does not explain the expected notation syntax or the number of rolls, and while an output schema exists, the description does not help connect inputs to outputs. The description needs more detail to be functionally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only vaguely references 'notation' and completely ignores the 'num_rolls' parameter. The description provides essentially no semantic information beyond the parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is essentially a restatement of the tool name ('roll dice') with a vague reference to 'given notation'. It communicates the basic action but adds no detail about what notation is or how it differs from other tools. It's minimally clear but not strongly differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, nor any context about suitable scenarios. The description simply states the action without implying any usage conditions or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_urlsB

Search through saved URLs by title, description, or original URL

ParametersJSON Schema
NameRequiredDescriptionDefault
search_termYes
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so the description carries full burden. It implies a read operation but does not explicitly state it is non-destructive, mention pagination, or disclose rate limits or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-front-loaded sentence with no redundant words. Every word adds meaning, making it efficiently scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema, the description is minimally adequate. It misses details like default limit, pagination, and scope but the output schema likely covers return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema parameter descriptions, the description adds value by explaining the search_term matches title, description, or URL. However, it does not clarify the limit parameter or its default behavior, leaving partial coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches through saved URLs by specific fields (title, description, original URL). This distinguishes it from sibling tools like 'web_search' (internet search) and 'get_url_metadata' (single URL lookup).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not indicate when to use this tool over alternatives such as 'list_my_urls' or 'web_search', nor does it mention context like user vs. workspace scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shorten_urlB

Shorten a URL using multiple services. Supports custom aliases and collections.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
custom_aliasNo
collection_nameNo
tagsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions 'multiple services' but does not specify which services, error behavior, rate limits, or authentication requirements. This is insufficient for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise at two sentences, with no unnecessary words or repetitions. It front-loads the primary action and then lists supported features.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters, no annotations, and no param descriptions in the schema, the description leaves significant gaps: it does not explain output format (even though output schema exists), limitations, or how to leverage multiple services. The description is too sparse for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate. It adds context for 'custom_alias' and 'collection_name' by mentioning aliases and collections, but 'tags' is not explained, and 'url' receives no additional detail. The description provides only minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Shorten a URL using multiple services.' It also specifies key features like custom aliases and collections, which distinguishes it from sibling tools such as expand_url or check_url_safety.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives (e.g., shorten_url_batch). Usage is implied by the features mentioned, but no context or exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shorten_url_batchC

Shorten multiple URLs at once. Separate URLs with newlines or commas.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlsYes
collection_nameNo
tagsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.5/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Lacks annotations and fails to disclose crucial behavioral traits like maximum batch size, error handling, or processing behavior. The description carries full burden but adds minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at two sentences, but the brevity sacrifices informational value. Could be slightly expanded without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description omits critical context for a batch operation such as result format, error handling, and any operational limits. Incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaning for the 'urls' parameter by specifying delimiters, but does not describe 'collection_name' or 'tags' at all. With 0% schema description coverage, this is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it shortens multiple URLs at once, with input format details. However, it does not explicitly distinguish from the sibling 'shorten_url' tool, which presumably handles single URLs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use batch vs individual shortening, no prerequisites, and no mention of alternatives. The description only explains input formatting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_urlB

Validate if a URL is properly formatted and reachable

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavior. It mentions 'reachable' but does not define what constitutes reachable (e.g., HTTP status, timeout duration) or address potential side effects like network calls or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no redundancy. However, it borders on under-specification; slightly more detail would improve it without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema, the description covers the core purpose but lacks specifics on error handling or edge cases (e.g., unreachable URLs). Adequate for a basic validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to compensate. The sole parameter 'url' is only named; no format, example, or constraints are provided beyond the type string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates if a URL is properly formatted and reachable. This verb+resource combination distinguishes it from sibling tools like check_url_safety (security) and expand_url (different operation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like check_url_safety, which also involves URL validation but with a safety focus. No when-not-to-use or prerequisite information is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 13 tool updatesv0.1.0
    • First observedcheck_url_safety
    • First observedcreate_url_collection
    • First observedexpand_url
    • First observedgenerate_qr_code
    • First observedget_url_metadata
    • First observedlist_collections
    • First observedlist_my_urls
    • First observedroll_dice
    • First observedsearch_urls
    • First observedshorten_url
    • First observedshorten_url_batch
    • First observedvalidate_url
    • First observedweb_search

TDQS

C2.9/5.0

Scored across 13 tools

Disambiguation3/5

Most tools have distinct purposes, but 'check_url_safety' and 'validate_url' overlap in URL checking, and 'roll_dice' is entirely unrelated to URL management, causing confusion.

Naming Consistency5/5

All tools use a consistent verb_noun pattern in snake_case (e.g., 'shorten_url', 'list_collections'), making the naming predictable and clear.

Tool Count3/5

13 tools is slightly high for a URL management server, especially with the inclusion of an irrelevant dice-rolling tool and a generic web search tool that could be considered out of scope.

Completeness3/5

The server covers core URL operations like shortening, expanding, and safety checks, but lacks basic CRUD operations such as deleting or updating URLs and collections, leaving notable gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    C
    maintenance
    Provides web search capabilities using the Tavily API, enabling AI models to search the internet and retrieve up-to-date information.
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables web search using Bing and DuckDuckGo combined, and fetching readable content from web pages, with no API key required.
    9 npm
    2
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Enables AI agents to perform real-time web searches and extract clean, LLM-readable content from URLs using the Tavily API.
    2
    MIT