Skip to main content
Glama

Rate an item

update_rating
DestructiveIdempotent

Set or update user rating in stars, 0.05 to 5.0 in steps of 0.05: half stars (e.g. 3.5), or a score out of ten divided by two (7.5/10 is 3.75).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "media_type": "<media_type>",
      "rating": "<rating>"
    },
    "name": "update_rating"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNoThe title to rate (exact title preferred; an ambiguous partial match returns candidates with ids instead of guessing)
ratingYesRating in stars, 0.05 to 5 in steps of 0.05: half stars (e.g. 3.5), or a score out of ten divided by two (5.5/10 is 2.75)
seasonNoShows only: rate this one season instead of the whole show (with episode, rate one episode).
episodeNoShows only, with season: rate this one episode. Rating an episode marks it watched.
item_idNoLibrary item id (UUID), as shown by get_details. When given, title is ignored and the row is addressed exactly.
media_typeYesType of media

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / media_type / enum
      Previous value: -[
      -  "book",
      -  "movie",
      -  "album",
      -  "show",
      -  "anime",
      -  "podcast",
      -  "game",
      -  "manga",
      -  "comic"
      -]New value: +[
      +  "book",
      +  "movie",
      +  "album",
      +  "show",
      +  "anime",
      +  "podcast",
      +  "game",
      +  "manga",
      +  "comic",
      +  "boardgame"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / media_type / enum
      Previous value: -[
      -  "book",
      -  "movie",
      -  "album",
      -  "show",
      -  "anime",
      -  "podcast",
      -  "game",
      -  "manga"
      -]New value: +[
      +  "book",
      +  "movie",
      +  "album",
      +  "show",
      +  "anime",
      +  "podcast",
      +  "game",
      +  "manga",
      +  "comic"
      +]
  3. Changed3 schema fields changed
    • changedInput schema / properties / rating / description
      Previous value: -"Rating from 0.5 to 5 stars, in half-star increments (e.g. 3.5)"New value: +"Rating in stars, 0.05 to 5 in steps of 0.05: half stars (e.g. 3.5), or a score out of ten divided by two (5.5/10 is 2.75)"
    • changedInput schema / properties / rating / minimum
      Previous value: -0.5New value: +0.05
    • removedInput schema / properties / rating / multipleOf
      Removed value: -0.5
  4. Changed6 schema fields changed
    • addedInput schema / properties / episode
      Added value: +{
      +  "description": "Shows only, with season: rate this one episode. Rating an episode marks it watched.",
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / item_id
      Added value: +{
      +  "description": "Library item id (UUID), as shown by get_details. When given, title is ignored and the row is addressed exactly.",
      +  "type": "string"
      +}
    • changedInput schema / properties / media_type / enum
      Previous value: -[
      -  "book",
      -  "movie",
      -  "album",
      -  "show",
      -  "anime"
      -]New value: +[
      +  "book",
      +  "movie",
      +  "album",
      +  "show",
      +  "anime",
      +  "podcast",
      +  "game",
      +  "manga"
      +]
    • addedInput schema / properties / season
      Added value: +{
      +  "description": "Shows only: rate this one season instead of the whole show (with episode, rate one episode).",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / title / description
      Previous value: -"The title to rate (partial match supported)"New value: +"The title to rate (exact title preferred; an ambiguous partial match returns candidates with ids instead of guessing)"
    • changedInput schema / required
      Previous value: -[
      -  "media_type",
      -  "title",
      -  "rating"
      -]New value: +[
      +  "media_type",
      +  "rating"
      +]
  5. Changed3 schema fields changed
    • changedInput schema / properties / rating / description
      Previous value: -"Rating from 1 to 5 stars"New value: +"Rating from 0.5 to 5 stars, in half-star increments (e.g. 3.5)"
    • changedInput schema / properties / rating / minimum
      Previous value: -1New value: +0.5
    • addedInput schema / properties / rating / multipleOf
      Added value: +0.5
  6. First observed

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds nothing behavioral beyond that: it does not say an existing rating is overwritten, that rating an episode marks it watched (a real side effect for a destructive tool), or that item addressing differs between title and item_id. What it does say about the value scale is a near copy of the schema's rating description.

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?

One front-loaded sentence with no filler or preamble. It is dense with parenthetical examples that duplicate the schema, which is minor waste rather than a structural flaw.

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 six-parameter, destructive mutation with no output schema, the description covers only the numeric scale and omits how an item is targeted (title vs item_id), the season/episode scoping rules, and the watched-marking side effect. The rich schema compensates, leaving the definition adequate but not self-sufficient.

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?

Schema description coverage is 100%, so the baseline is 3. The description only elaborates the rating scale — and the out-of-ten division rule is already stated verbatim in the schema's rating property — while saying nothing about title, item_id, season, episode, or media_type.

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?

"Set or update user rating in stars" gives a concrete verb plus resource and implies both creation and overwrite semantics. It does not name or distinguish itself from the sibling clear_rating or get_by_rating, so an agent must infer the boundary, but the core operation is unambiguous.

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 statement of when to use this tool instead of clear_rating, get_by_rating, or set_rating_names, and no guidance on prerequisites or whether a prior rating must exist. The word "update" hints at replacement behavior but this is inference, not guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources