Skip to main content
Glama
YangLiangwei

PersonalizationMCP

by YangLiangwei
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_user_top_items

Retrieve a user's top artists or tracks from Spotify based on time range (4 weeks, 6 months, or years) and item limit. Choose between short, medium, or long-term listening history.

Instructions

Get user's top artists or tracks.

    Args:
        item_type: "artists" or "tracks"
        time_range: "short_term" (4 weeks), "medium_term" (6 months), "long_term" (years)
        limit: Number of items to return (1-50, default 50)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNo
item_typeNotracks
time_rangeNomedium_term
access_tokenNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It indicates a read operation ('Get') but does not mention authentication requirements (e.g., needing a valid Spotify access_token), potential errors for invalid item_type or expired tokens, or that it operates on the authenticated user's data. It also fails to describe the response format or any side effects. This significant gap leaves the agent uncertain about prerequisites and failure modes.

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 concise and well-structured. The first sentence states the purpose clearly, followed by a clean list of parameters with explanations. There is no redundancy or wasted words, making it easy for an agent to parse quickly.

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 not complete enough for an agent to call this tool correctly. It omits the crucial access_token parameter semantics, including how to obtain or supply it, and does not indicate what the returned data will look like (since there is no output schema). Given the tool's complexity (OAuth-based, multiple options), these gaps are material and could lead to failed or misinterpreted calls.

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 three of four parameters: item_type ('artists' or 'tracks'), time_range (with durations), and limit (with range and default). However, it omits any explanation for access_token, which is a required aspect of the tool given its OAuth-dependent context. Since schema description coverage is 0%, the description must compensate fully, but it only partially does so.

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 a specific verb and resource: 'Get user's top artists or tracks.' This uniquely identifies the tool among siblings, none of which cover 'top items.' The inclusion of parameter explanations further reinforces the purpose, making it immediately distinguishable from tools like get_user_recently_played or get_user_saved_tracks.

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 explicit guidance on when to use this tool versus alternatives. While the purpose implies its use case, there are no mentions of alternative tools or conditions that would make this tool preferable. The agent is left to infer context from the tool name and sibling list, which is insufficient.

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

Deploy Server

Other Tools