Retrieve track details from the stats.fm catalog using a track ID. Choose concise, detailed, or JSON output to get track information for analysis or integration.
Look up a track in the stats.fm catalog by id
| Name | Required | Description | Default |
|---|---|---|---|
| track_id | Yes | stats.fm track id | |
| response_format | No | 'concise' = human prose, 'detailed' = more fields in prose, 'json' = raw API object | concise |
Changes observed during successful MCP inspections.
v1.29.0Does 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 only states 'Look up' which implies a read-only operation, but does not disclose what is returned, whether it can fail (e.g., track not found), any rate limits, or that it is safe/non-destructive. The lack of any return description or error handling leaves the agent uncertain about side effects and outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no waste. It is appropriately sized for a simple lookup tool, though it might be slightly too terse. Structure is clear and front-loads the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters, the schema already covers parameters and response_format hints at output formatting. However, there is no output schema, so the description does not explain what a successful lookup returns. While the response_format parameter implies output types, the description does not explicitly state the return payload structure. This is a moderate gap for a tool that is otherwise straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both track_id and response_format are already well-documented in the schema. The description adds only 'by id' which reinforces track_id but adds no new meaning. Since the schema handles the parameter details, the description meets the baseline without compensation being needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Look up'), a specific resource ('a track in the stats.fm catalog'), and the key identifier ('by id'). It distinguishes itself from siblings like statsfm_catalog_artist and statsfm_catalog_album, and from get_track which likely refers to Spotify. An agent can identify the tool's purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when you have a stats.fm track id) but does not explicitly differentiate from alternatives. For example, it doesn't state when to use this instead of statsfm_search for finding a track, or versus statsfm_track_stats for statistics. The 'by id' hint is present but no explicit when/not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.