Trakt MCP server

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

Annotations already signal destructiveHint and idempotentHint; the description goes beyond them by pinning down exactly what is destroyed (the stored token) and what the resulting state is (forgotten). It doesn't cover side effects like rate limits or required auth, but those are not strongly needed for a zero-parameter clear operation.

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?

Seven words, front-loaded action, no filler. Every phrase ('revoke', 'stored token', 'forget it') adds a distinct piece of meaning.

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 parameterless destructive operation with an output schema and annotations covering idempotence and destructive behavior, this is complete. An agent has enough information to know what will happen and when to call it.

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?

The tool takes zero parameters and schema description coverage is 100%, so there is nothing for the description to add. The description does clarify that the token in question is the stored authentication token, which is useful context.

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?

States a concrete action: 'Revoke the stored token' and the end state 'forget it.' This clearly separates it from start_authentication and finish_authentication, which establish credentials rather than clear them.

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 use case is implied—call this when the stored authentication token should no longer be used—but there is no explicit when/why guidance or comparison with siblings like create_oauth_revoke. It offers no exclusions, yet also names no alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful workflow detail: the body's expected fields must be discovered by reading the matching GET or /schema endpoint. It doesn't describe side effects, auth requirements, or idempotency behavior, but with annotations present a 3 is appropriate.

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 very short and front-loaded with the purpose. The endpoint line and the body note each add useful information without fluff or redundancy. Every sentence earns its place.

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 tool with a hidden, openWorld body and an output schema present, the description provides the essential discovery mechanism by directing the agent to the GET or /schema endpoint. It doesn't explain the domain meaning of 'check into an item' or the relationship to delete_checkin, but the agent has enough to invoke it correctly with the schema guidance.

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?

The schema only defines 'body' as a free-form object with additionalProperties true and zero descriptions. The description compensates by explaining that body is the request payload and by pointing the agent to the matching GET or /schema endpoint to learn the expected fields. This is meaningful guidance for an openWorld parameter.

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 clearly states the verb 'Check into' and the resource 'an item' via the POST /checkin endpoint. It conveys the core action, though it does not explicitly distinguish create_checkin from sibling tools like create_scrobble_start or delete_checkin.

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 gives no guidance on when to use this tool versus alternatives such as delete_checkin or the scrobble endpoints. It only instructs the agent to read the matching GET or /schema endpoint before sending a request, which is procedural but not comparative.

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

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

The annotations already convey that this is not read-only, not destructive, and idempotent. The description adds no behavioral context beyond that, such as authentication requirements, side effects, response behavior, or what happens on duplicate posts. It does not contradict the annotations.

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 compact and front-loaded: the core action comes first, followed by endpoint and parameter guidance. There is no filler or redundant prose.

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 create operation with a nested, opaque body parameter and no output schema explanation, the description is thin. It does not state what a comment is attached to, which fields are required, whether authentication is needed, or what the response contains, so the agent must rely on external lookups.

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?

The schema has a single unconstrained 'body' object with 0% description coverage. The description only labels it as 'Request payload' and tells the agent to consult another endpoint for fields, which is a discovery workaround rather than actual semantic meaning. It does not compensate for the missing schema documentation.

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 opens with 'Post a comment' and gives the explicit endpoint 'POST /comments/', clearly identifying both the action and the resource. It is not a tautology and an agent can tell this creates a comment, though it does not explicitly contrast with sibling comment tools like create_comments_by_id_replies.

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?

There is no guidance about when to use this tool instead of the many related comment tools. The only advice is to read the matching GET or /schema endpoint for body fields, which is about parameter discovery, not tool selection or usage context.

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

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

Annotations already indicate this is a non-readonly, idempotent, non-destructive write, but the description adds no behavioral context beyond restating 'Like a comment' and the POST route. It does not mention authentication, side effects, whether duplicate likes are ignored, or how the like can be removed.

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 brief and front-loaded: a one-line purpose, the exact endpoint, then a compact args list. Every sentence earns its place and there is no redundant filler.

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 two-parameter tool with an output schema and annotations, this is minimally adequate: purpose, endpoint, and id semantics are present, and the body field is delegated to schema discovery. However, it is incomplete as a standalone guide because it lacks selection guidance and does not explain behavioral expectations around liking, so an agent must infer those from the annotations and siblings.

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 coverage is 0%, so the description must compensate. It does add some value: id is described as 'id/slug of the resource,' and body is described as a request payload with an explicit instruction to consult the matching GET or /schema endpoint for expected fields. This is useful but leaves the actual body contract undefined, requiring the agent to perform further discovery.

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 opens with the specific action 'Like a comment' and backs it with the exact route POST /comments/{id}/like. This clearly identifies the resource (a comment) and the operation (adding a like), and it is distinct from sibling actions like reporting, replying, or removing a like.

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?

There is no guidance about when to choose this tool over alternatives such as delete_comments_by_id_like, create_comments_by_id_reactions, or the other comment creation tools. The only process guidance is to read a GET or /schema endpoint before supplying the body, which addresses parameter discovery, not tool selection.

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

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

Annotations already disclose non-readOnly, idempotent, non-destructive behavior, so the description does not need to restate them. The description adds the useful instruction that the body schema should be fetched from the matching GET or /schema endpoint, but it does not explain the result of re-adding a reaction or auth requirements.

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 compact and organized into a one-line purpose, HTTP route, and a short Args list. The Args lines mostly restate the input schema, but they are not verbose enough to hurt.

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 mutation with an opaque free-form body, the description provides the route, parameters, and a discovery mechanism for body fields. However, an agent still cannot know what reaction_type values are accepted or what responses/lifecycle apply without external lookup.

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 coverage is 0%, and the description only labels id/reaction_type as path parameters and body as a payload. It gives no valid reaction_type values or body field semantics, although the pointer to the matching GET/schema endpoint partially compensates.

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 opens with 'Add comment reaction,' a clear verb+resource combination, and the path line reinforces exactly which comment and reaction are targeted. It does not contrast with sibling tools such as create_comments_by_id_like or delete_comments_by_id_reactions_by_reaction_type, but the 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.

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

No explicit when-to-use or alternatives are given; the agent is left to infer this is the reaction-creation counterpart of the delete tool and distinct from like. The only usage note is to inspect the matching GET/schema for body fields, which is procedural rather than selection guidance.

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

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

The description adds a valuable workflow instruction: 'Read the matching GET or the /schema endpoint first to see the fields this resource expects.' This goes beyond the annotations, which already indicate non-read-only, non-destructive, idempotent, and open-world behavior. The description complements these with practical guidance on body construction, but does not cover auth or error handling.

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 remarkably concise—two sentences plus the HTTP path. It front-loads the purpose and essential guidance without redundancy. Every sentence earns its place, and the body-preparation hint is included efficiently.

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?

Given the tool's simplicity, the description, along with the annotations and an output schema, provides sufficient guidance. It covers the action, path, and the key hint for body construction. It omits specific error handling or authentication details, but these are likely covered generically. The description is adequate for an agent to invoke the tool correctly.

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?

The schema has no descriptions and body is freeform, so the description must compensate. It explains id as 'id/slug of the resource' and directs the agent to consult GET/schema for body fields, which is crucial for correct invocation. However, it could be more explicit about what the id refers to (comment id) and the exact expected body structure.

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 specific action ('Post a reply for a comment') and clearly identifies the resource (a comment). It explicitly distinguishes this from reading replies (get_comments_by_id_replies) and creating a new comment (create_comments) by using 'reply' and the path. The name reinforces this.

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 when replying to a comment but does not explicitly contrast this tool with alternatives or provide conditions for use. There is no guidance on when not to use it or mention of prerequisites. It relies on the path and name to signal intent, which is adequate but not explicit.

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

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

Annotations cover readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is already known. The description adds the POST method and a pointer to discover the body schema, but it does not disclose side effects (e.g., whether reports are anonymous, require authentication, or are rate-limited). There is no contradiction with annotations.

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 brief and front-loaded with the primary action. It includes the endpoint, the two arguments, and a necessary hint for building the body. No filler or redundancy.

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 report action with an output schema present and annotations covering safety, the description provides enough to invoke correctly: the resource path, the id parameter, and a route to learn about the body. An agent can proceed without missing critical details, though a little more context about what 'report' implies (e.g., moderation) would make it fully unambiguous.

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 0%, so the description must compensate. It explains 'id' as 'The id/slug of the resource' and for 'body' it tells the agent to read the GET or /schema endpoint to discover fields. This is useful but stops short of describing the actual body structure; it offloads discovery to runtime rather than giving explicit semantics.

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 and resource: 'Report a comment.' The endpoint 'POST /comments/{id}/report' confirms the exact action and resource type. It doesn't explicitly differentiate itself from similar report siblings like create_episodes_by_id_report, but the resource is explicit enough to avoid confusion.

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 gives no guidance on when to use this tool versus alternatives like create_movies_by_id_report or create_users_by_id_report. It does mention a prerequisite ('Read the matching GET or the /schema endpoint...') but fails to state the context or exclusions that would help an agent choose this operation.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the HTTP method and endpoint but nothing else—no authentication, rate limits, side effects, or what the report submission entails. It provides minimal value beyond the annotations.

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 brief and structured with an Args section. The endpoint line is redundant with the tool name but not harmful. It is efficient, though the endpoint duplication could be trimmed.

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 write operation with a nested object body, the description is thin. It does not explain what reporting an episode does, what happens on success, or any prerequisites beyond reading the GET/schema. The output schema exists, so return format is covered, but the description lacks essential behavioral context for a mutation tool.

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?

The schema has zero descriptions, so the description must compensate. It describes 'id' as 'id/slug' and instructs the agent to read the GET or /schema endpoint to understand the body fields. This is useful but does not detail the body structure itself, so it only partially fills the gap.

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 the action ('Report') and the resource ('an episode') clearly, and the noun 'episode' distinguishes it from sibling report tools for movies, shows, lists, etc. However, it does not elaborate on what 'report' means or why one would use it.

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?

There is no guidance on when to use this tool versus the many sibling report tools. No alternatives, conditions, or exclusions are mentioned. The description is purely functional and does not help an agent decide between this and, say, create_shows_by_id_report.

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

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

Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond that – it does not explain the effect of liking a list, idempotency implications, authentication requirements, or what happens on repeated calls. Since the description carries only minimal additional transparency, it falls short.

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 short and to the point: a one-line purpose, the exact endpoint, and a compact Args section. It front-loads the core action and avoids filler. The Args guidance is a little terse but still earns its place.

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 like endpoint with an open-world body and an output schema available, the description gives just enough direction: the id parameter is explained, and the body's open nature is addressed by directing to a GET or schema reference. However, it does not mention required body fields, authentication, or the relationship with sibling like/unlike endpoints, leaving some gaps for proper invocation.

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 0%, so the description must compensate. It adds that id is 'The id/slug of the resource' and instructs the agent to read the matching GET or /schema endpoint to discover the body fields. This provides more meaning than the bare schema, though it does not enumerate body fields themselves, leaving significant discovery work to the agent.

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 clearly states the verb and resource: 'Like a list' with the endpoint POST /lists/{id}/like. It is specific and unambiguous about what action is performed. However, it does not distinguish this from the sibling create_users_by_id_lists_by_list_id_like, which also likes a list but in a different context, so it misses full sibling differentiation.

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?

There is no guidance on when to use this tool versus alternatives such as delete_lists_by_id_like or create_users_by_id_lists_by_list_id_like. The only extra instruction is to read the matching GET or /schema endpoint for the body fields, which is parameter discovery, not usage context. No conditions or exclusions are provided.

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

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

Annotations already indicate idempotent, non-destructive, mutating behavior. The description adds no behavioral detail beyond the fact that it reports a list; it does not mention side effects, permissions, or response expectations, so it contributes little beyond annotations.

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 very short and front-loaded with the core purpose. It includes the endpoint and argument explanations without fluff, though it may be too terse for critical information.

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?

Despite having an output schema and annotations, the description is incomplete for an agent deciding when to invoke this tool. It lacks any context about what reporting entails, how it differs from similar report tools, or any usage conditions, leaving the agent to infer.

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?

The description clarifies that 'id' is an id/slug and that 'body' is a payload to be built after consulting the GET or /schema endpoint. Since the body schema is an open object with no defined fields, this pointer is essential and adds value, though it does not enumerate any actual fields.

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 the verb 'Report' and the resource 'a list', with the endpoint POST /lists/{id}/report making the target explicit. It is not a tautology but is extremely brief and does not differentiate from the many sibling report tools beyond the resource type.

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 provides no guidance on when to use this tool versus alternatives like create_users_by_id_lists_by_list_id_report. The only instruction is to read the GET or /schema endpoint to construct the body, which addresses the body parameter but not tool selection or context.

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

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

The description does add a behavioral trait by stating 'images: Also queue a refresh of the resource images,' implying asynchronous queuing behavior. Annotations already provide idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description does not disclose other potential side effects or rate limits, but it is consistent with annotations.

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 compact and well-structured: a clear one-line purpose, the endpoint path, and a concise parameter list. Every sentence earns its place, and the guidance to read the matching GET or schema is a practical inclusion without unnecessary verbosity.

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 mutation tool with a complex body parameterached, the description offers a workable strategy by directing the agent to the schema endpoint for field definitions. The output schema exists, so return values are covered elsewhere. However, it lacks sibling differentiation and does not mention that body is required, though the input schema makes that clear. Overall, it is sufficiently complete for correct invocation.

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 0%, so the description is the only source of parameter meaning. It provides a meaningful explanation for each parameter: id as 'id/slug', body as a payload requiring external reference, and images as a queue flag. The body explanation is somewhat indirect—pointing to GET/schema rather than listing fields—but it does add value beyond the bare schema.

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 action—'Refresh movie metadata'—with a specific resource (movies). It is not a tautology and conveys the core purpose. However, it does not explicitly differentiate from the sibling tool create_movies_by_id_refresh_justwatch, leaving that distinction to the name and inference.

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 only usage guidance is 'Read the matching GET or the /schema endpoint first to see the fields this resource expects,' which is a prerequisite for constructing the body param, not a when-to-use guideline. There is no mention of when to choose this tool over refresh_justwatch or other refresh variants, so selection criteria are absent.

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

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

Annotations already indicate a non-destructive, idempotent write operation, so the description does not contradict them. It adds the specific target of the write (JustWatch links), but it does not disclose side effects, auth requirements, rate limits, or what refreshing entails beyond the resource name. This is adequate but not rich 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.

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

The description is short and front-loaded, with the purpose stated first, followed by the endpoint and arguments. Every line earns its place, especially the body-discovery instruction. It could be slightly more explicit about which GET endpoint is 'matching,' but the structure is clean.

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 two-parameter tool with annotations and an output schema present, this is adequate for making the call: it provides the endpoint, id semantics, and a strategy for constructing the body. It lacks when-to-use guidance and behavioral detail, but those gaps are not fatal to basic invocation.

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?

With 0% schema description coverage, the description compensates meaningfully: it clarifies that id can be an id or slug, and it tells the agent to consult the matching GET or /schema endpoint to discover body fields. This prevents guessing on an open 'body' object, though the actual body fields are not enumerated.

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 specific action ('Refresh') and an exact resource ('movie JustWatch links'), making the tool's purpose immediately clear. This also distinguishes it from siblings such as create_movies_by_id_refresh (general movie refresh) and create_shows_by_id_refresh_justwatch (shows, not movies). The POST endpoint line reinforces the 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 gives no guidance about when to choose this tool over alternatives like create_movies_by_id_refresh or create_shows_by_id_refresh_justwatch. The only contextual advice is to read a GET or /schema endpoint before supplying the body, which is about payload construction, not tool selection. Usage context is only implied by the name.

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

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

The description adds no behavioral context beyond what annotations already signal. It does not explain what 'report' does, what side effects occur, whether authentication is needed, or what the response represents. Annotations indicate readOnly=false and idempotent=true, but the description itself contributes no extra behavioral transparency.

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 compact and well-structured, with a clear one-line purpose, the endpoint, and an Args section. Every line earns its place with no filler.

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?

It is minimally viable for invocation: the agent knows the endpoint, the id parameter, and how to discover body fields. However, it lacks a clear definition of 'report', usage guidance, and behavioral side effects. Annotations and output schema cover some gaps, but not all.

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?

Despite 0% schema description coverage, the description gives useful semantics: id is the id/slug and body is a request payload whose fields should be discovered via GET or /schema. This is especially valuable because the body schema is open-ended with additionalProperties.

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?

'Report a movie' names a specific verb and resource, and the endpoint POST /movies/{id}/report makes the operation concrete. It is distinguishable from sibling report tools by the movie resource, though 'report' itself is somewhat ambiguous (flag vs. generate report).

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?

No guidance is given for when to use this tool versus alternatives. The instruction to read the matching GET or /schema endpoint is about constructing the body, not about choosing this tool over sibling report tools.

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

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

Annotations already indicate readOnlyHint=false (write operation), openWorldHint=true (potential side effects), idempotentHint=true, and destructiveHint=false. The description adds only the HTTP method and a pointer to read the schema. It does not disclose what happens on success, whether authentication is needed, rate limits, or any side effects beyond the annotation hints. The openWorldHint signals possible side effects, but the description does not elaborate, leaving the agent with little behavioral context beyond the annotations.

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 very concise—two short sentences plus a parameter note. It front-loads the core action ('Add notes') and the HTTP method, and the parameter guidance is placed after. There is no wasted verbosity, and the structure is clear. However, it could be more informative without losing conciseness, hence a slight deduction from a perfect score.

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?

Given the tool's complexity (openWorldHint, free-form body, nested objects) and that an output schema exists (though not shown), the description is sparse. It does not explain what a 'note' is, typical fields (e.g., text, timestamp, user), authentication requirements, or the expected response. The pointer to the schema is useful but does not provide immediate context. For a write tool with open-world semantics, this is insufficient for an agent to call it correctly without additional resources.

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?

The schema defines a single 'body' parameter as an object with additionalProperties: true, meaning it is free-form, and schema description coverage is 0%. The description tells the agent to 'Read the matching GET or the /schema endpoint first to see the fields this resource expects,' which compensates by pointing to where field definitions can be found. This adds value beyond the schema, but it does not enumerate any specific fields, so the agent still lacks direct knowledge of what to include.

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 'Add notes.' which is a clear verb and resource, and the HTTP method POST /notes further clarifies the action. It is unambiguous as a creation operation, especially given sibling tools like update_notes_by_id and delete_notes_by_id. However, it does not explicitly contrast with other create-like tools (e.g., create_comments) or mention the scope (user-specific? global?), so it lacks explicit sibling differentiation.

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 instructs 'Read the matching GET or the /schema endpoint first to see the fields this resource expects,' which provides a practical usage guideline for constructing the request. However, it offers no guidance on when to choose this tool over alternatives (e.g., update vs. create) or any exclusions. The usage context is implied but not explicitly contrasted with other note-related tools.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description's 'Generate' action aligns with a non-read, non-destructive mutation — no contradiction. The description adds the endpoint and the open-world body hint, but with annotations already carrying the safety profile, it contributes modest additional context about the operation's effect.

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 compact — an action sentence, the endpoint, and a brief args block. The action is front-loaded. The 'POST /oauth/device/code' line is slightly redundant with the tool name but reinforces the resource. Minimal waste overall.

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?

The tool has an output schema (covering return values) and a nested, open-world body. The description provides a pointer to /schema for fields, which helps. But it lacks OAuth flow context — the agent won't know this pairs with create_oauth_device_token or create_oauth_token, nor the sequencing, which matters given the many sibling auth tools.

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 0%, so the description must compensate. It names the single parameter ('body: Request payload') and directs the agent to the /schema endpoint for field definitions, which is reasonable given the open-world (additionalProperties=true) body. However, it does not enumerate any actual body fields or expected structure, leaving the agent to fetch schema elsewhere.

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 specific action ('Generate new device codes') and the resource (OAuth device code). This is distinct from sibling tools like create_oauth_device_token, create_oauth_revoke, and create_oauth_token, which the name and verb differentiate. However, it doesn't explicitly call out how it differs from create_oauth_device_token, leaving some ambiguity about the OAuth flow steps.

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 tells the agent to 'Read the matching GET or the /schema endpoint first to see the fields this resource expects,' which is useful for body construction. But it provides no when-to-use guidance, no flow context (e.g., that device-code generation precedes token exchange), and doesn't mention alternatives. The usage is only implied from the tool name.

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

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

Annotations already provide the safety profile (non-read-only, idempotent, non-destructive), so the description's job is lighter. 'Poll' usefully implies repeated safe calls, but the description does not disclose behavior on pending or expired codes, required authentication, or rate-limit implications.

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 compact and front-loads the essential action ('Poll for the access_token') before the endpoint and parameter guidance. It omits important context, but it is not verbose or padded.

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?

The description fails to explain the OAuth device flow ordering, such as obtaining a device code first and then polling with that code. The body requirements are left entirely to the schema, and while an output schema exists, the critical call semantics are not conveyed.

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 coverage is 0% and the single body parameter is an unconstrained object with additionalProperties true. The description merely labels it as 'Request payload' and directs users to the schema, so it does not communicate what fields are actually needed, such as device_code or grant_type.

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 and resource: 'Poll for the access_token.' and identifies the exact endpoint POST /oauth/device/token. It does not explicitly contrast with the sibling OAuth token tools, but the core action is distinct and unambiguous.

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?

No guidance is given about when to use this tool versus create_oauth_device_code or create_oauth_token. The only usage instruction is a generic pointer to read the /schema endpoint, with no mention of the device-flow prerequisite or that this should be called repeatedly after obtaining a device code.

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

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

Annotations already cover readOnly, idempotent, and destructive hints. The description adds the HTTP method and a pointer to the schema endpoint, but doesn't explain the consequences of revoking (e.g., token invalidation, re-auth). It's acceptable but not rich.

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 concise with a clear purpose, endpoint, and args section. It's front-loaded with the action. The redirect to schema is a bit of a detour but keeps it short.

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 revoke operation, it's missing context like when to use, prerequisites (having an active token), and error handling. However, output schema may cover response format. The description is functional but not comprehensive.

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 coverage is 0%, so description must compensate. It provides a generic instruction to read the GET or /schema endpoint for fields, but doesn't list actual parameters or examples. This is minimal guidance but not zero.

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 clearly states the verb 'Revoke' and the resource 'access_token', making the purpose unambiguous. It also includes the HTTP endpoint, which is helpful. Though it doesn't differentiate from siblings, the purpose is clear.

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?

No guidance on when to use this tool or alternatives. It doesn't mention scenarios like token expiry, security, or comparison with create_oauth_token. The agent is left to infer when revocation is appropriate.

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

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

Annotations indicate idempotentHint=true, which is notable for a token creation endpoint, but the description doesn't explain what idempotency means here or any side effects. The description also doesn't disclose that this is an OAuth token exchange that likely returns access/refresh tokens, or whether it invalidates previous tokens. With no annotation details beyond hints, the description carries the burden of behavioral disclosure and fails to provide meaningful context.

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 short and front-loaded with the endpoint, but it includes a somewhat cryptic instruction to 'Read the matching GET or the /schema endpoint first.' This is not self-contained and may not be actionable for an agent. It's concise but not optimally structured; the pointer to external schema discovery is a workaround rather than a clear explanation.

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 an OAuth token exchange tool with a single open-object parameter and no output schema details, the description is incomplete. It doesn't explain the OAuth flow, what the body should contain, what the response will be, or how this tool relates to the authentication lifecycle (start_authentication, finish_authentication, create_oauth_device_code, etc.). An agent would struggle to call this correctly without external documentation.

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 0%, and the only parameter 'body' is an open object with additionalProperties: true. The description says 'Read the matching GET or the /schema endpoint first to see the fields this resource expects,' which is a pointer to external documentation rather than actual parameter semantics. It does not explain what fields the body should contain (e.g., grant_type, code, redirect_uri, client_id, client_secret). The description adds minimal value beyond the schema, and the agent is left without concrete guidance.

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 says 'Exchange a token' and includes the HTTP endpoint POST /oauth/token, which conveys the resource and action. However, it doesn't explain what kind of token is being exchanged, what it is exchanged for, or how this relates to the OAuth flow. The name 'create_oauth_token' and the endpoint make the purpose somewhat clear, but the description itself is thin and doesn't distinguish it from sibling OAuth tools like create_oauth_device_code, create_oauth_device_token, or create_oauth_revoke.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention the OAuth flow context, prerequisites (e.g., needing an authorization code or device code first), or when to use create_oauth_device_token or create_oauth_revoke instead. The only hint is the endpoint path, which an agent would have to infer meaning from.

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

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

Annotations already declare idempotent and non-destructive behavior. The description adds useful context beyond those: it mentions queueing image refreshes and directs the agent to discover body fields from another endpoint. This helps set expectations about asynchronous work and schema discovery.

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 compact and front-loaded with the core purpose, followed by the endpoint and a clean Args list. Every line adds value, with no redundant content.

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?

The description covers the essential call pattern, body requirements, and optional image refresh. With an output schema present, return-value details are unnecessary. Minor gaps remain around side effects and prerequisites, but the provided guidance is sufficient for a tool of this complexity.

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?

Despite 0% schema description coverage, the description provides meaningful explanations for all three parameters. id is clarified as id/slug, body is explained as a dynamic payload with a discovery path, and images is described as an optional queue trigger. This is strong compensation for the bare schema.

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?

"Refresh person metadata" is a specific verb+resource that clearly distinguishes this from sibling tools like create_movies_by_id_refresh or create_people_by_id_report. The endpoint is also explicitly stated, leaving no ambiguity about what the tool targets.

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 gives no guidance on when to choose this tool over similar refresh or report tools. It only implies usage from the purpose phrase. The body instruction tells the agent to consult GET/schema, but that is parameter preparation, not tool-selection guidance.

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

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

Annotations already indicate the tool is non-read-only, idempotent, and non-destructive. The description adds a useful behavioral note: to consult the GET or /schema endpoint for expected fields, which clarifies the need for external documentation. However, it does not disclose what the report action does (e.g., whether it notifies moderators, is reversible, or has side effects) beyond what annotations cover.

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 extremely short but is under-specified rather than concisely effective. The opening 'Report a person' is too vague, and the rest is a terse list of arguments without elaboration. It is structured clearly but fails to deliver necessary information in a compact yet sufficient manner.

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?

Given the tool has nested objects, an output schema, and zero schema descriptions, the description is far from complete. It offloads critical information to external endpoints (GET /schema) without even hinting at the return shape. An agent cannot correctly invoke this tool without additional investigations, making it incomplete for a well-defined operation.

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?

With 0% schema description coverage, the description must compensate for parameter meaning. It explains 'id' as 'the id/slug of the resource' but for 'body' it merely says 'Request payload' and points to the GET /schema endpoint for details. This defers understanding rather than providing actual semantics, leaving the body structure unexplained and requiring the agent to perform extra lookups.

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 'Report a person' is ambiguous—it could mean either retrieving a report or submitting one. The endpoint 'POST /people/{id}/report' implies a write operation, and the tool name includes 'create', but the description does not explicitly state that it creates a report. It also does not differentiate from siblings like create_movies_by_id_report or create_comments_by_id_report, which share a similar pattern.

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 does not provide any guidance on when to use this tool versus alternatives. It only instructs to read the GET or /schema endpoint to understand the request body, which is a preparation step but not a usage condition. No exclusions or alternative tool mentions are present.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive mutation. The description adds that it pauses watching and gives the endpoint, but it does not disclose prerequisites such as an active scrobble/session or side effects on playback progress. This is acceptable given the annotations, though not rich.

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 compact and front-loaded: a one-sentence summary, the endpoint, and a single parameter hint. Every line earns its place and there is no filler.

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 one-parameter, open-body tool with an output schema and annotations covering idempotency and safety, the description is mostly complete. It tells the agent where to learn the body shape, but it is incomplete in not situating pause within the broader scrobble lifecycle relative to start and stop.

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?

The schema only provides a generic required 'body' object with additionalProperties true. The description labels it as a request payload and instructs the agent to read the matching GET or /schema endpoint to discover expected fields, which is important given the 0% schema description coverage. It does not enumerate fields, but that is reasonable for an open-world body.

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 opening line 'Pause watching in a media center' names a specific action and target resource, and the POST /scrobble/pause endpoint anchors it clearly. It is distinguishable from siblings like create_scrobble_start and create_scrobble_stop, though it does not explicitly contrast with them.

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?

There is no guidance about when to use this tool instead of create_scrobble_start or create_scrobble_stop, nor any indication of the pause/stop distinction. The only conditional instruction is about reading the GET or /schema endpoint for body fields, which is parameter guidance, not usage guidance.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds a behavioral cue by instructing the agent to read the matching GET or /schema endpoint first, which is useful for an open-world payload. It does not contradict annotations, but it does not disclose side effects or response behavior beyond that.

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 brief, direct, and front-loaded with the primary purpose before the endpoint and argument notes. It earns each line, though it could have added one sentence for alternatives or usage context without bloating.

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?

Given the output schema and annotations, the description does not need to explain return values or safety. However, it leaves out important invocation context: authentication requirements, when to use start vs pause/stop, and what constitutes a valid scrobble start payload. The pointer to /schema helps but is a deferral rather than complete context.

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?

The schema provides only an opaque 'body' object with 0% property coverage. The description compensates by labeling it 'Request payload' and explicitly directing the agent to the matching GET or /schema endpoint for the expected fields. This is genuinely helpful for an open-ended body parameter, though no concrete field names are given.

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 specific action ('Start watching') and resource ('in a media center'), backed by the explicit POST /scrobble/start endpoint. It is clear enough as an operation, but it does not explicitly distinguish itself from create_scrobble_pause, create_scrobble_stop, or create_checkin.

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 gives no guidance on when to use this tool versus related scrobble/checkin operations. It does not mention alternatives, prerequisites, or the scrobble lifecycle. The agent must infer context from sibling tool names.

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

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

Annotations already cover idempotent and non-destructive hints, and the description adds that this operation stops or finishes watching. However, it does not disclose auth requirements, response behavior, or what happens to an active scrobble state.

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 compact and front-loaded with the action and endpoint, followed by a useful payload-discovery instruction. There is no filler or redundant elaboration.

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?

The /schema pointer and annotations provide a reasonable basis for invoking the tool, especially with an open-world body parameter and an output schema present. Still, it lacks usage differentiation among scrobble tools and any mention of prerequisites or side effects, so it is not fully self-sufficient.

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?

The schema only exposes an opaque 'body' object with additionalProperties=true, so the description must compensate. It correctly identifies body as the request payload and instructs the agent to consult the matching GET or /schema endpoint, but it does not list or exemplify expected fields.

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 specific action, 'Stop or finish watching in a media center', and provides the endpoint POST /scrobble/stop. It semantically distinguishes itself from siblings like create_scrobble_start and create_scrobble_pause, though it does not explicitly reference them.

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?

There is no guidance on when to use this tool versus alternatives such as create_scrobble_pause or create_scrobble_start. The only directive is to read the matching GET or /schema endpoint first, which addresses payload discovery rather than tool selection.

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

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

Annotations already signal non-read-only, idempotent, and non-destructive behavior, so the description needs to add behavioral context. It only adds the endpoint and a request-payload note, with no mention of side effects, authentication, or what happens on repeated calls. This does not contradict annotations but also does not enrich them.

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 short and front-loaded, with the action and endpoint stated first. The Args section is minimal but purposeful, and no filler or redundant schema repetition is present.

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?

The tool has an output schema, so return-value details are not required. However, the body is an open object with no inline field documentation, and the description depends entirely on an external /schema lookup. It also omits broader context about how recent searches relate to the sibling search endpoints.

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 coverage is 0%, so the description must compensate. It identifies 'body' as the request payload and directs the agent to the matching GET or /schema endpoint to discover expected fields. This is helpful, but the description still does not explain the actual fields or any body structure.

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 'Add recent search' uses a specific verb and resource, and the endpoint 'POST /search/recent/' confirms it is a create operation. It is distinguishable from the sibling create_search_recent_remove, though it does not explain what a 'recent search' semantically contains.

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 instruction to read the matching GET or /schema endpoint is a useful how-to for body construction, and the action implies when to use the tool. However, there is no explicit guidance about when this tool should be preferred over sibling search-related tools or what the alternative conditions are.

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

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

Annotations already cover idempotency and destructive hint. The description adds that it's a POST operation and instructs to read the GET/schema for fields, but provides no side effects, return values, or additional behavioral context, contributing minimal value beyond annotations.

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?

Two concise sentences with no fluff. It front-loads the action and resource, includes the endpoint, and mentions the argument. Though minimal, it is efficiently structured.

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?

The tool has an output schema, but the description doesn't mention return values. The open-ended body is left completely unexplained, requiring external lookup. For a removal operation, it lacks sufficient context for correct invocation without additional resources.

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?

The sole parameter 'body' is an open-ended object with no schema description (0% coverage). The description says to read the matching GET or /schema endpoint, but does not provide any actual field information or structure, deferring entirely instead of compensating for the undocumented payload.

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?

States the verb 'Remove' and resource 'recent search', clearly indicating the action. However, it does not differentiate from sibling tools like create_search_recent beyond the obvious opposite, and doesn't clarify what a 'recent search' entry is or whether it removes all or a single entry.

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?

No guidance on when to use this tool versus alternatives or other remove operations. It only gives the endpoint and points to schema for payload, without explaining scenarios, prerequisites, or conditions that would select this tool.

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

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

Annotations include readOnlyHint:false, destructiveHint:false, idempotentHint:true, openWorldHint:true (partial). The description states the action 'report' which implies it creates a report or flags the resource, which aligns with readOnlyHint:false (it's a write operation) and not destructive. It adds that the body fields should be read from the matching GET endpoint, providing context on what to send. It does not detail side effects (e.g., what happens after reporting) but annotations cover the safety profile partially (not destructive, idempotent).

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 short and front-loads the purpose with the endpoint and HTTP method, followed by parameter definitions. It is concise with no filler, but the guidance to read GET endpoints is placed after parameter definitions, which is acceptable. The structure is rational for the given information.

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?

Given the tool has only two parameters and an output schema exists, the description covers the essential call pattern but relies heavily on external references (GET and /schema) for body content. For a reporting operation, it should clarify what constitutes a valid report (e.g., reason, comment) to avoid misuseikuha, but the pointer to GET is a workaround. The output schema may provide return information, so completeness is moderate.

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 0%, and the description provides minimal parameter info: it says 'id' is the id/slug and 'body' is the request payload but doesn't explain the structure beyond pointing to the GET endpoint. The schema shows 'body' is an object with additionalProperties true, so the fields are not predefined, and the description's guidance to read the GET endpoint is necessary. However, it doesn't describe any specific fields or formatting, leaving the agent to infer them from the referenced endpoints.

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 clearly states it reports a season via POST /seasons/{id}/report, and the name 'create_seasons_by_id_report' aligns with that. It specifies the resource (season) and the action (report), distinguishing it from other report tools for different resources (e.g., create_movies_by_id_report). However, it doesn't explicitly contrast with siblings, but the resource is clear.

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?

It instructs to read the matching GET or /schema endpoint to know the fields the body expects, giving clear context for what to do before calling. While it doesn't explicitly state when not to use this tool or name alternatives, the instruction to consult the GET endpoint implies this is for reporting a season when that action is needed, and the presence of sibling report tools for other resources provides implicit context.

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

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

The description adds minimal behavioral detail beyond the POST method and the action 'Reset show progress.' It does not explain what resetting entails (e.g., whether it clears all episode progress), nor does it note any side effects. Annotations already indicate mutability (readOnlyHint false) and non-destructive nature, so the description adds little novel context.

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 compact and well-structured: it starts with the purpose, then the HTTP method and path, then annotated arguments. Every sentence serves a purpose with no redundancy. The reading order is logical and easy to follow.

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?

Given that an output schema exists and annotations provide mutability flags, the description covers the basics for invoking the tool. However, it lacks clarity on what 'reset' actually does (e.g., scope of progress cleared) and how it differs from the delete sibling. The direction to read the schema compensates for the opaque body, but the overall context is incomplete for a nuanced decision.

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?

The description enriches the 'id' parameter by noting it can be an id or slug, which the schema does not. For 'body', it provides a helpful strategy (read the matching GET or /schema endpoint) to discover expected fields, but does not enumerate them. Since schema coverage is 0%, this pointer is valuable but still leaves the agent to investigate further.

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 clearly states 'Reset show progress.' which is a specific action on a show's watched progress. It names the resource and verb. However, it does not explicitly differentiate from the sibling delete_shows_by_id_progress_watched_reset, and the 'create_' prefix in the name could be misleading, though the description clarifies the intended action.

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?

No guidance is given on when to use this tool versus alternatives. The description only instructs reading a GET or /schema for the body fields, which is about payload construction, not selection of this endpoint. There is no mention of prerequisites, exclusions, or when to prefer this over the delete counterpart.

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

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

The description adds behavioral detail beyond annotations, such as the image queue side effect when the 'images' parameter is set, and advises reading the GET/schema endpoint to understand the body fields. It does not contradict the annotations (readOnlyHint false, idempotentHint true, destructiveHint false).

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 compact and front-loaded with the purpose, followed by the endpoint and parameter details. No extraneous content.

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?

The description covers the required parameters, side effects, and prerequisites. It omits whether the refresh is synchronous or asynchronous, but the existence of an output schema mitigates the need to describe return values. Overall, it is adequate for a refresh operation.

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?

With 0% schema coverage, the description compensates by explaining each parameter: 'id' as the resource slug, 'body' with instruction to consult GET, and 'images' as queuing image refresh. This adds meaningful context that the schema lacks.

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 specific verb ('Refresh') and resource ('show metadata'), which clearly distinguishes it from the justwatch refresh sibling. It is not a tautology and gives a precise action.

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?

No guidance is provided on when to use this tool versus alternatives like create_shows_by_id_refresh_justwatch. It only mentions reading the GET endpoint first, which is a prerequisite, not a usage condition or exclusion.

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

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

The annotations already cover the safety profile (non-read-only, idempotent, non-destructive), so the description does not need to repeat those. It adds the scope 'JustWatch links' but does not disclose whether refresh replaces existing data, fetches from an external source, has rate limits, or has other side effects.

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 compact and front-loads the purpose, then provides the endpoint and argument guidance. The endpoint line is slightly redundant with the tool name but still useful for clarity and does not waste much space.

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?

The description is minimally adequate for a two-parameter mutation tool, especially since an output schema exists. However, it leaves gaps around when a refresh is appropriate, what side effects occur, and how the body should be shaped beyond the GET/schema pointer. More context would help an agent invoke it confidently.

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?

With 0% schema description coverage, the description compensates meaningfully by explaining id as 'id/slug' and giving an actionable strategy for body: read the matching GET or /schema endpoint. While body fields are not enumerated, the guidance tells the agent how to discover them, which is valuable for an open-world body object.

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 specific verb ('Refresh') and a precise resource scope ('show JustWatch links'), which clearly distinguishes it from siblings like create_shows_by_id_refresh and create_movies_by_id_refresh_justwatch. The included POST endpoint reinforces the exact action 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 gives no guidance on when to use this tool versus related alternatives such as create_shows_by_id_refresh or create_shows_by_id_report. It only instructs the agent to read the matching GET or /schema endpoint, which addresses body construction, not tool selection.

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

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description does not contradict them. It adds a modest behavioral cue — that this is a POST mutation whose payload shape is defined by the matching GET/schema — which is useful for the openWorld body parameter. However, it adds little else beyond what the annotations convey, so with the annotations doing the heavy lifting a 3 is appropriate.

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 compact and clearly formatted (endpoint, then args), with no wasted words. But it is under-specified rather than concisely complete: the one-line purpose 'Report a show' is thin and the body guidance, while helpful, is generic and could apply to any endpoint. It is efficient in length but the content is minimal.

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?

An output schema exists, so return-value explanation is not required, and the description's pointer to the GET/schema endpoint mitigates the openWorld body field. The main gap is purpose ambiguity — the agent still does not know what a 'report' is or what the tool accomplishes. For a 2-parameter tool this is adequate but not complete, so a 3 fits.

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 0%, so the description carries the full burden, and it compensates reasonably. It explains id is 'the id/slug of the resource' and, crucially, tells the agent to read the matching GET or /schema endpoint to discover the body fields — essential because body has additionalProperties:true and the schema itself documents nothing. This is genuinely helpful guidance for an otherwise opaque free-form payload.

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 verb and resource ('Report a show') plus the endpoint, so it is not a tautology. However, 'report' is ambiguous — it is never clarified whether this submits an abuse report, requests a content report, or something else. It also does not differentiate itself from many sibling report tools (create_episodes_by_id_report, create_movies_by_id_report, create_seasons_by_id_report), which are identical in form.

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 gives no when-to-use guidance, prerequisites, or exclusion conditions. With roughly a dozen sibling report tools, the agent gets no signal about which resource type each one targets beyond the name, and no instruction on when to prefer this over the GET variants. The 'Read the matching GET or the /schema endpoint first' line is the only guidance, and it is about parameter lookup, not tool selection.

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

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

Annotations already indicate this is a non-destructive, idempotent mutation, so the description does not need to restate those traits. It adds a useful instruction to read the matching GET or /schema endpoint before supplying the body, but it does not explain side effects, authentication needs, or what 'report' actually does beyond the bare statement.

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 short and front-loaded with the core action. The endpoint line and Args list are redundant with the tool name and schema, but they are presented cleanly and do not add unnecessary prose.

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?

The output schema and annotations reduce the need for the description to explain return values or mutation safety. The body-discovery instruction is a useful workaround for the open-world body schema, but the description still lacks report semantics, usage context, and any guidance on what the endpoint actually accomplishes.

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?

With 0% schema description coverage, the description carries the parameter documentation burden. It explains id as an id/slug, season and episode as numbers, and body as a request payload whose fields should be discovered via GET or /schema. This is helpful but the body parameter remains opaque and no report-specific fields are suggested.

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 specific action and resource: 'Report an episode.' The endpoint path reinforces that this targets an episode within a show/season. However, it does not differentiate itself from sibling report tools such as create_episodes_by_id_report or create_shows_by_id_report, and 'report' is ambiguous without context.

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?

There is no guidance on when to use this tool versus the many related report endpoints, such as create_shows_by_id_report or create_seasons_by_id_season_report. The description provides no conditions, exclusions, or alternatives, so an agent must infer usage entirely from the name and endpoint.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds no behavioral context beyond 'Report a season.' It does not disclose what the report does, side effects, or requirements. The instruction to read GET/schema is a parameter hint, not a behavioral disclosure. No contradiction with annotations.

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 succinct and front-loaded with the purpose, followed by the endpoint and parameter explanations. Each part earns its place with no redundant content. It could be slightly more explanatory without much cost, but it is appropriately sized for a tool with a simple operation.

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?

The tool has an output schema and three required parameters; the description provides enough to call it, including guidance on obtaining body fields. However, it lacks guidance on when to use this specific report tool over siblings like create_seasons_by_id_report, leaving a potential selection ambiguity. The description is adequate but not complete in terms of tool selection context.

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 0%, so the description must compensate. It explains each parameter: id (the id/slug of the resource), season (season number), and body (request payload, with a pointer to the GET or /schema endpoint for field details). This adds meaningful meaning beyond the bare schema labels, though it does not enumerate expected body fields.

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 specific verb and resource ('Report a season'), which is clear and distinct from tools targeting other resources. However, it does not differentiate from the sibling tool create_seasons_by_id_report, which also reports a season but via a different endpoint. The resource is clearly a season within a show context, but this is implied only by the path, not stated.

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?

No guidance is provided on when to use this tool versus alternatives like create_seasons_by_id_report or other report tools. The only guidance is to read the matching GET or /schema endpoint for the body fields, which addresses parameter usage rather than tool selection. There is no mention of context, prerequisites, or exclusions.

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

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

Annotations already communicate that this is a mutating, idempotent, non-destructive operation, and the description is consistent with them. The description adds little behavioral nuance beyond the verb 'add' and the payload-discovery instruction; it doesn't mention duplicate handling, partial failures, or authentication requirements.

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 short, front-loaded with the core action, and contains no filler. The 'POST /sync/collection' line is somewhat redundant with the tool's name/purpose, but the overall structure is efficient.

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?

Annotations and the presence of an output schema cover safety and return shape, but the opaque body leaves a major gap. The pointer to 'the matching GET or /schema endpoint' is vague given the many sync collection siblings, and the description doesn't convey what a valid collection-sync payload should contain or how additions behave.

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?

The only parameter, body, is an opaque additionalProperties object with 0% schema description coverage. Calling it a 'request payload' mostly restates the schema, and telling the agent to read the schema endpoint is a workaround rather than actual parameter semantics. The description does not compensate for the empty body schema.

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 specific action ('Add items') and a resource ('collection'), which matches the tool name and distinguishes it from the obvious counterpart create_sync_collection_remove. It doesn't explicitly mention 'sync' or name a sibling, so it's clear but not fully differentiated.

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 use case is implied: use this when adding items to a collection. The description also gives a prerequisite ('Read the matching GET or the /schema endpoint first'), which is helpful. However, it doesn't explicitly say when to prefer this over related sync create/update/remove tools, nor does it name the exact matching GET.

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

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

The annotations already establish this is a non-read (readOnlyHint=false), idempotent, non-destructive write, so the bar for extra disclosure is lower. The description adds the concrete HTTP endpoint (POST /sync/collection/remove) and the prerequisite to read the matching GET or /schema response before calling. It does not describe effects on sync state or whether removals are permanent, but that is partially covered by destructiveHint=false. No contradiction with annotations.

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 compact: a purpose sentence, the endpoint, and one argument line with guidance. Purpose is front-loaded, and each line earns its place. No filler or repetition of the schema's structural details.

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 write tool with a free-form body, the description's pointer to the /schema endpoint and matching GET is the right level of guidance, and the output schema exists so return-value details need not be explained. It is adequate but leaves gaps: it never clarifies whether items are identified by ID or full objects, or whether this is a batch operation, relying on the agent to fetch the schema first.

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 0% and body is an opaque additionalProperties:true object, so the description must compensate. It identifies body as the request payload and, crucially, routes the agent to the matching GET or /schema endpoint for field discovery — genuinely useful given the schema gives zero field information. It still omits the actual expected fields and any item-shape or batch semantics, leaving discovery as a homework step.

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?

States a specific action and resource ('Remove items from collection'), which clearly distinguishes the collection target from sibling _remove tools like create_sync_watchlist_remove, create_sync_favorites_remove, or create_sync_history_remove. Naming the resource itself carries the differentiation. However, it does not explicitly contrast with the inverse sibling create_sync_collection, and some clarity comes from parsing the tool's own name.

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 use case is implied by the verb and resource — call this when the user wants to remove items from their sync collection rather than add or list them. It offers a prerequisite ('Read the matching GET or the /schema endpoint first') but gives no explicit when-to-use or when-not-to-use guidance versus the sibling create_sync_collection or the list_sync_collection_* endpoints.

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

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

The description adds no behavioral context beyond the annotations. It repeats a mutating action ('Add') and the POST method, but annotations already indicate not read-only, not destructive, idempotent, and open-world. No additional side effects, authentication needs, or rate limits are disclosed.

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 compact, puts the purpose first, and has no filler. The endpoint line and body instruction are each informative, so every sentence earns its place.

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?

The description is not self-contained: it doesn't identify which GET is 'matching', doesn't explain the relationship to update/remove/reorder siblings, and leaves the body contract to an external schema discovery step. Annotations and output schema help, but an agent still lacks enough context to call this reliably without extra lookups.

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?

The schema only says body is an open object, and the description adds that body is the request payload and directs the agent to the matching GET or /schema endpoint for actual fields. This is useful for an open-world body but does not enumerate any specific expected fields, so it only partially compensates for 0% schema coverage.

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 clearly states 'Add items to favorites' and gives the endpoint POST /sync/favorites, making the core action and resource unambiguous. It doesn't explicitly contrast with sibling tools like update_sync_favorites or remove variants, so it falls short of the strongest differentiation.

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?

No guidance is given about when to use this tool versus the many related tools (create_sync_favorites_remove, create_sync_favorites_reorder, update_sync_favorites, etc.). The only instruction is to read a GET/schema endpoint for body fields, which is about payload construction, not tool selection.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description does not contradict them. It adds the endpoint (POST /sync/favorites/remove) and a workflow hint to read the matching GET or /schema endpoint first. It does not disclose effects, reversibility, or auth requirements, but with annotations present the bar is lower and the added context earns a pass.

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 compact and front-loaded with the purpose line, followed by the endpoint and a terse args note. Each line earns its place; there is no filler or repeated schema content. Slightly formulaic in its 'Args:' layout but appropriately sized.

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?

Given a single opaque body parameter, the description's pointer to GET/schema is a practical workaround-tenacity . With an output schema present, return values need no explanation. The main gap is the absence of any comparison to sibling favorites tools (add/reorder/update), which would materially help an agent choose and construct the call correctly in this large sibling set.

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 coverage is 0%: the body property is an opaque object with additionalProperties:true and no description. The description compensates somewhat by identifying body as the 'request payload' and directing the agent to the matching GET or /schema endpoint for the expected fields. This is useful but gives no actual field-level semantics for this specific favorites-removal payload.

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 specific verb and resource: 'Remove items from favorites.' This disambiguates the confusing 'create_' prefix in the tool name-new . It clearly signals a removal operation. However, it does not explicitly differentiate from siblings like create_sync_favorites (add) or update_sync_favorites, leaving the agent to infer the relationship from the name alone.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention that create_sync_favorites adds items, that reorder variants exist, or what makes removal distinct. Among a sibling set with add/reorder/update favorites variants, the agent gets only the implied usage from the verb 'Remove' and no exclusions or routing hints.

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

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

Annotations already indicate the tool is not read-only (readOnlyHint=false), is idempotent (idempotentHint=true), and not destructive (destructiveHint=false). The description adds a note about reading the schema first, which is more about input preparation than behavioral transparency. It does not disclose any side effects, ordering semantics, or whether the operation replaces or appends the entire list. Minimal value added over annotations.

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 very short and to the point: a one-line purpose, the endpoint, and a brief note on the body. It is front-loaded with the action and does not waste words. However, it is so sparse that some might argue it is under-specified rather than concise, but for what it says, it is efficiently structured.

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 reorder operation, the description is completely inadequate. It does not explain what the body should contain (e.g., an ordered list of IDs), how to specify the new order, or any expected response. It points to the schema but does not provide enough context for an agent to correctly construct the request. With an open schema (additionalProperties true) and no parameter descriptions, the description fails to give any useful operational context.

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?

The only parameter is 'body', described merely as 'Request payload' with a pointer to look at a GET or schema endpoint. This adds no actual meaning about the structure or required fields; it essentially defers all semantics to an external resource. Given schema coverage is 0%, the description should compensate by explaining what the body contains, but it does not.

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 ('Reorder') and resource ('favorited items'), but it is vague about scope. It does not explicitly say these are 'sync favorites' (only the endpoint reveals that), and it does not distinguish itself from other reorder tools like create_sync_watchlist_reorder or create_users_by_id_lists_by_list_id_items_reorder. The purpose is clear enough for a simple action, but not specific enough to differentiate among the many sibling tools.

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?

No guidance is provided on when to use this tool versus alternatives. The only instruction is to read a GET or /schema endpoint for the request payload, which is a generic prerequisite, not a usage guideline. There is no mention of prerequisites, when to avoid it, or any exclusions.

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

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

Annotations already establish that this is a mutating, idempotent, open-world, non-destructive call. The description adds the concrete effect ('Add items to watched history'), the exact endpoint, and guidance to discover the expected body shape before sending, which is useful operational context beyond the annotations. There is no contradiction.

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 tightly structured: a one-sentence purpose, the endpoint, and a brief Args note. All information is front-loaded and every line earns its place. There is no redundant filler.

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 an open-world POST with an output schema, annotations covering idempotence/safety, and an opaque body parameter, the description provides enough orientation: what the tool does, where it posts, and how to discover the required fields. It does not detail authentication or success responses, but the output schema and explicit schema-discovery instruction cover the main gaps.

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?

The schema only exposes an opaque required body object with additionalProperties allowed, and schema description coverage is 0%. The description compensates by labeling body as the request payload and instructing the agent to consult the matching GET or /schema endpoint to learn expected fields. This is meaningful, actionable guidance for an open-world body.

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 specific verb and resource: 'Add items to watched history.' It also gives the exact endpoint (POST /sync/history), making the tool's role clear and distinguishing it from related sync tools that handle collection, ratings, watchlist, or removal.

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 intended use is explicit: use this tool when you want to add items to a user's watched history. It also provides a clear prerequisite by telling the agent to read the matching GET or /schema endpoint before constructing the body. It does not explicitly compare against create_sync_history_remove, but the operation is unambiguous enough that this is not a major gap.

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

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

The description adds little beyond the operation name and endpoint; it doesn't describe side effects, response behavior, or why the operation is idempotent. The annotations already indicate idempotentHint and destructiveHint, but the description itself contributes no further 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.

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

The description is short, front-loaded, and every line serves a purpose. The HTTP path and prerequisite are useful, though the path partly repeats the tool name without adding much.

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 an open-world body schema, the pointer to the matching GET and /schema endpoint is essential and present, and an output schema exists so return values are covered. Still, it omits what kind of history items are expected and any authentication or prerequisite details, leaving it short of fully self-contained.

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?

With 0% schema description coverage, the description needed to compensate, but it only labels body as 'Request payload' and points to the GET/schema endpoint. This is actionable but doesn't explain expected fields, structure, or item identifiers, so the agent still must perform an external lookup.

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 the specific action 'Remove items from history' and includes the HTTP path, which distinguishes it from generic CRUD tools. However, it doesn't explicitly connect the tool to sync history or contrast it with sibling removal tools like create_sync_collection_remove or create_sync_watchlist_remove.

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 gives a clear context for use—removing history items—and provides a prerequisite: read the matching GET or /schema endpoint first. It does not explicitly explain when to choose this tool over its many sibling remove tools, leaving some selection inference to the agent.

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

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

Annotations already indicate a mutating, non-destructive, idempotent operation, and 'Add new ratings' is consistent with them. The description adds the endpoint and the schema-discovery instruction, but does not explain side effects, auth requirements, or response behavior beyond what annotations imply.

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 compact and front-loaded: action, endpoint, and argument guidance are each stated in a short line with no filler. Every sentence earns its place.

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?

Given the open-world body, the presence of an output schema, and annotations covering safety/idempotency, the description provides the key missing information: how to discover the expected body fields. It could say more about the semantics of ratings, but it is adequate for correct invocation.

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?

The schema only defines body as an open object, so the description's direction to 'Read the matching GET or the /schema endpoint first' is the main semantic contribution. It compensates for the 0% schema coverage by pointing the agent to an authoritative source, though it does not enumerate actual fields.

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 action and resource: 'Add new ratings,' reinforced by the explicit POST /sync/ratings endpoint. It is distinguishable from sibling operations like create_sync_ratings_remove and get_sync_ratings_by_type_by_rating, though it does not name alternatives.

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?

Usage is implied: use this tool to add new ratings. The instruction to read the matching GET or /schema endpoint first is helpful preparation, but the description does not explicitly state when to prefer this over related sync tools or when not to use it.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the endpoint and a note to read the matching GET or /schema endpoint first, which is useful context for understanding the request payload. However, it does not disclose what 'remove' does beyond the obvious, whether it is a bulk removal, or what the response contains. The description does not contradict the annotations, but it also does not add much behavioral depth beyond what the annotations already imply.

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 short and front-loaded with the core action 'Remove ratings.' The endpoint and the pointer to the GET/schema endpoint are useful and concise. It earns its place, though the 'Args: body' line is somewhat redundant with the input schema.

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?

Given the tool has one opaque body parameter, no output schema details in the description, and a confusing name, the description is not complete enough. The pointer to the GET/schema endpoint is a good start, but an agent still lacks information about what ratings are removed, whether the operation is scoped to a user, and what a successful response looks like. The output schema exists but the description does not summarize it.

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 0%, and the only parameter is 'body' with additionalProperties: true, so the schema provides no field-level detail. The description tells the agent to read the matching GET or /schema endpoint to see expected fields, which is a helpful pointer, but it does not describe the body structure, required fields, or example payload. With 0% coverage, the description should compensate more than it does.

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 says 'Remove ratings' and gives the endpoint POST /sync/ratings/remove. This states a clear verb and resource, but the tool name 'create_sync_ratings_remove' is confusingly prefixed with 'create_' while the description says 'Remove'. It does not distinguish itself from the sibling create_sync_ratings (which likely adds ratings) beyond the endpoint path, and the name/title mismatch adds 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 gives no guidance on when to use this tool versus alternatives. It does not mention that create_sync_ratings is the counterpart for adding ratings, nor does it explain the relationship to get_sync_ratings_by_type_by_rating or other sync tools. The only hint is the endpoint path, which is not enough for an agent to decide when to call this tool.

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

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

Annotations already signal idempotency and non-destructiveness. The description adds the concrete behavior that this is a POST to /sync/watchlist and that the body fields should be discovered from the schema/GET endpoint. It does not discuss duplicate handling or response details, but annotations lower the burden here.

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 compact and front-loaded: one action sentence, the endpoint, then the body guidance. There is no filler, and every line earns its place.

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 single-parameter endpoint with an output schema and annotations covering idempotency, the description gives the essential invocation path and directs the agent to the schema for the flexible body. It is slightly incomplete in not naming the corresponding GET or common body examples, but the open-world body may not be enumerable statically.

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?

The input schema only provides an opaque body object with additionalProperties true, so the description's note that body is the request payload and to read the matching GET or /schema for expected fields adds useful meaning. However, it does not describe any concrete fields or shapes, leaving the agent dependent on another endpoint.

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 specific action and resource: 'Add items to watchlist' and gives the exact endpoint POST /sync/watchlist. It distinguishes the add behavior from sibling remove/reorder tools primarily through the verb 'Add', but it does not explicitly name those alternatives.

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 usage is implied: use this tool to add items to the watchlist. It also provides a prerequisite by saying to read the matching GET or /schema endpoint first, but it does not explicitly say when to prefer this over update/remove/reorder siblings or give exclusions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description adds the endpoint and the advice to consult GET/schema, but no additional behavioral details (e.g., whether removal is permanent, any side effects, or authentication requirements). It does not contradict the annotations, but it does not enrich them.

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 brief: one line for purpose, one for the endpoint, and a short argument note. It is not padded with filler, though the 'Args: body: Request payload.' line is somewhat redundant with the schema. Overall, it is efficiently sized.

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 write operation with an open body schema and an output schema, the description is underspecified. It does not explain what the response will contain, what errors might occur, or how to construct the request beyond pointing to external docs. Given the complexity of the sync resource and the presence of siblings, the description leaves too much to discovery.

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?

The input schema has a single 'body' object with additionalProperties:true, offering zero field definitions (0% schema coverage). The description compensates partially by directing the agent to 'the matching GET or the /schema endpoint first,' but it does not actually describe what fields the body expects (e.g., item IDs to remove). This is a significant gap for a tool that requires a structured payload.

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 clearly states the verb and resource: 'Remove items from watchlist.' It also provides the HTTP endpoint, making the operation unambiguous. However, it does not explicitly distinguish itself from similarly-named siblings like create_sync_watchlist (which adds) or create_sync_watchlist_reorder, though the verb 'remove' differentiates reasonably.

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?

No guidance on when to use this tool versus alternatives. It does not mention that this is for removing specific items (as opposed to clearing the watchlist) or how it relates to other sync operations like create_sync_collection_remove. The only instruction, 'Read the matching GET or the /schema endpoint first,' is about field discovery, not usage context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the mutation safety profile. The description adds the HTTP method (POST) and instructs the agent to consult the GET/schema endpoint for expected fields, but does not disclose reorder behavior details such as how ordering conflicts are resolved or whether existing order is replaced wholesale.

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?

Three short sentences with the purpose front-loaded. The HTTP method and the Args pointer each earn their place, and there is no filler or repetition of schema data.

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?

An output schema exists, so return-value documentation is not required. The main gap is that the body payload semantics are delegated entirely to the /schema endpoint, and with an opaque body schema the agent must make an extra call to invoke this correctly; sibling differentiation is also absent.

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 0% and the body parameter is an opaque object with additionalProperties: true, so the description carries the burden. It partially compensates by calling body a "Request payload" and directing the agent to the matching GET or /schema endpoint for field details, but it does not describe any actual fields or structure expected in the payload.

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?

"Reorder watchlist items." uses a specific verb and resource, clearly stating what the tool does. The action+resource combination distinguishes it from siblings like create_sync_watchlist, create_sync_watchlist_remove, and create_sync_favorites_reorder, though it does not explicitly name those alternatives.

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 when to use the tool (reordering watchlist items) and adds a prerequisite: "Read the matching GET or the /schema endpoint first to see the fields this resource expects." However, it provides no explicit when-not-to-use guidance or named alternatives among the many create_sync_* siblings.

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

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

Annotations already declare idempotentHint=true obtainable and destructiveHint=false, but the description adds no behavioral context beyond the action itself. It does not disclose side effects (e.g., preventing interactions), required permissions, or response behavior. Since the description is responsible for supplementing annotations, this is a gap.

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 concise and well-structured: purpose first, then endpoint, then args. Each line serves a clear function, and there is no fluff. The body guidance is slightly indirect but still efficient.

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?

The description adequately covers id and provides a discovery path for body fields via the GET/schema endpoints. With an output schema and annotations present, the tool is usable, but it lacks any note about side effects or when to choose this over related actions. It is acceptable but not fully self-contained.

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?

The id parameter is well described as 'the slug that identifies the user, or me for the authenticated user', which adds meaning beyond the schema's bare string type. The body parameter is described as a request payload with guidance to read the matching GET or /schema endpoint, but no concrete fields are listed, leaving the agent to fetch schema elsewhere.

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 clearly states the action and resource: 'Block this user.' and includes the endpoint POST /users/{id}/block, making the verb and target unambiguous. It does not explicitly differentiate from sibling tools like delete_users_by_id_block, but the action itself is specific enough to avoid confusion in most cases.

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?

There is no guidance about when to use this tool versus alternatives. The description does not mention conditions for blocking, prerequisites, or the companion unblock operation (delete_users_by_id_block). An agent has to infer usage from the tool name and endpoint.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that this creates a follow relationship and advises consulting the schema/GET before sending a body, but it does not disclose side effects, auth requirements, or rate-limit considerations. No contradiction with annotations.

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 compact and well-structured: a one-sentence action summary, the endpoint, and an Args block. It contains no filler and front-loads the primary behavior.

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 follow operation, with an output schema present and openWorldHint enabled, the description covers the essential call pattern: identify the user and supply a body learned from the schema or matching GET. It leaves the body's exact shape undisclosed and does not mention the reverse delete action, but the tool is simple enough that this is adequate.

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 0%, so the description must compensate. It usefully defines id as a user slug or 'me' for the authenticated user. For body, it only calls it a 'request payload' and points to the matching GET or /schema endpoint, which is helpful discovery guidance though not a direct field list.

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 opens with 'Follow this user' and gives the explicit endpoint POST /users/{id}/follow, naming a specific action and resource. This clearly distinguishes it from sibling tools like create_users_by_id_block or delete_users_by_id_follow.

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 intended use is implied by the action name, but there is no explicit guidance on when to choose this tool over alternatives, when not to use it, or what prerequisites apply. No mention of authentication or the corresponding unfollow operation.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the agent knows it's a non-destructive write. The description adds no behavioral context beyond that; it only says 'Create personal list' and instructs to read GET/schema for fields, which is more about parameter discovery. No disclosure of side effects, authentication requirements, or reversibility.

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 extremely concise, with a one-line purpose, an endpoint, and two argument descriptions. It front-loads the purpose and then gives technical details. Every sentence is minimal with no wasted words, though it may be too sparse for a complex operation. Still, it is efficient and structured.

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?

Given that the body parameter is an open object and there are many related list operations, the description is incomplete. It doesn't explain what constitutes a 'personal list' or how it differs from a smart list. It relies on the agent to consult other endpoints for field details, adding friction. It also doesn't mention response format, though an output schema exists. Overall, an agent would need additional research to use this tool correctly.

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?

The schema describes id and body, but body is an open object with no defined fields. The description adds the guidance to 'Read the matching GET or the /schema endpoint first to see the fields this resource expects.' This helps an agent discover the expected body structure, which is valuable given the schema provides no details. However, it doesn't specify any actual fields, so it's a pointer rather than a full explanation.

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 and resource: 'Create personal list.' It also provides the endpoint POST /users/{id}/lists. The term 'personal list' distinguishes it from smart lists (e.g., create_users_by_id_smart_lists), though it could be more explicit about what a personal list entails. The purpose is clear enough for an agent to understand the action.

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 offers no guidance on when to use this tool versus alternatives like create_users_by_id_smart_lists or update_users_by_id_lists_by_list_id. It doesn't mention any prerequisites, exclusions, or conditions. An agent has no basis to choose this tool over others in the same domain.

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

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

Annotations already flag this as a non-read-only, non-destructive, idempotent operation, and the description's 'Add' is consistent with them. It adds useful context that the mutation targets a 'personal list' and points the agent to schema discovery, but it does not disclose response behavior, side effects, or auth requirements. No contradiction with annotations.

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 short and front-loaded with the core action before the endpoint and args. The POST path and Args block are slightly redundant with the tool name and schema, but they are compact and do not bury the useful schema-discovery instruction.

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 mutation with an open body schema, the instruction to consult the matching GET or /schema endpoint is a practical route to the missing payload fields. However, the description still leaves item format, allowed types, and user/list id semantics to that discovery step, so it is adequate but not fully self-contained. An output schema exists, so lack of a return-value description is acceptable.

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 0%, so the description must carry parameter semantics. It only labels id and list_id as 'Path parameter' and body as 'Request payload,' which adds no real meaning; the body's actual item fields are deferred to 'the matching GET or the /schema endpoint.' This is a pointer rather than a semantic explanation.

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 opening sentence 'Add items to personal list' names a concrete verb and resource, so an agent immediately knows this tool appends items to a user's list. It does not explicitly distinguish itself from the remove/reorder siblings, but the 'Add' verb makes the intended operation unambiguous.

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 when to use it ('Add items...') and gives one operational prerequisite: 'Read the matching GET or the /schema endpoint first to see the fields this resource expects.' It does not say when-not-to-use or name alternatives such as create_users_by_id_lists_by_list_id_items_remove/reorder, so selection guidance is only implicit.

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

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

The annotations already indicate a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description's 'Remove items' is consistent with these and adds no further behavioral context, such as whether removal is permanent or requires authentication. Since annotations cover the safety profile, the description adds minimal extra value, but it is not contradictory.

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 exceptionally concise: one action sentence, the endpoint, and a three-item args list with a useful pointer to the schema. Every element earns its place with no fluff, and the core action is front-loaded.

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?

Despite having an output schema, the description is thin for a tool with an open body and no param documentation. It fails to explain what items can be removed, any constraints or prerequisites, or the response format. The pointer to GET/schema is a workaround but does not make the description complete on its own.

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?

With 0% schema coverage, the description must compensate. It lists id and list_id as path parameters (redundant with schema) and instructs to read the GET or /schema endpoint for the body fields. This pointer is helpful for the open body object, but it does not describe the expected shape or provide any field details, leaving the agent to discover them.

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 action: 'Remove items from personal list.' This is a specific verb and resource, distinguishing it from siblings like the add-items tool (create_users_by_id_lists_by_list_id_items) and reorder. It also includes the HTTP endpoint for clarity. However, it does not explicitly name alternative tools or scope, so it is not a 5.

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 provides no guidance on when to use this tool versus the add-items or reorder tools, nor any prerequisites such as ownership of the list. It only gives the endpoint and args, leaving the agent to infer usage from the name and context.

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

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

Annotations already convey readOnly=false, idempotent=true, destructive=false; the description adds no behavioral context beyond 'reorder', such as auth requirements, effect on existing order, or response. It does not contradict annotations.

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?

Three short, information-dense pieces: one-line purpose, exact path, and per-argument notes. No filler or repetition.

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 reorder operation with a free-form body, the description gives enough to start (endpoint, id semantics, where to look for body schema) but is not self-contained: list_id is undefined and the body fields are explicitly deferred. Annotations and output schema cover safety and return shape, so this is borderline-adequate.

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?

The description clarifies id ('me' or slug) and tells the user to consult GET/schema for the body fields, which is helpful given the body is an opaque additionalProperties object. However, list_id is only labeled 'Path parameter' with no list identifier semantics, and the reorder payload's required fields are not described.

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 first sentence names the exact operation ('Reorder') and resource ('items on a list'), which is specific and matches the endpoint. It doesn't explicitly contrast with sibling reorder/create endpoints, but 'items' and the full path disambiguate it from create_users_by_id_lists_reorder and item add/remove tools.

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?

No guidance on when to choose this over siblings such as create_users_by_id_lists_reorder or create_users_by_id_lists_by_list_id_items_remove. The only usage hint is to read GET/schema for body fields, which is a discovery instruction, not a use-case discriminator.

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

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

Annotations already signal that this is a mutating, idempotent, non-destructive call, and the description does not contradict them. However, beyond 'Like a list', it adds no behavioral detail such as whether liking is toggled, what state changes occur, or authentication requirements.

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 short and front-loaded with the action, followed by the endpoint and an Args list. It contains minimal waste, though repeating parameter names from the schema is somewhat redundant.

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?

The definition is adequate for a straightforward like action: id and list_id are mostly clarified, and body handling is deferred to a schema lookup. It is less complete on when to select this tool over sibling like/delete endpoints and on actual body fields, but the endpoint, annotations, and output schema cover the core invocation.

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?

With 0% schema description coverage, the description must compensate and partially does: it explains that id is a user slug or 'me' and points to GET/schema for the body shape. list_id only gets 'Path parameter' and body remains unspecified, so the agent still needs a schema lookup.

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 opening 'Like a list' plus POST /users/{id}/lists/{list_id}/like states a concrete action and resource: liking a user's list. It is clear what the tool does, though it does not explicitly distinguish itself from sibling like endpoints such as create_lists_by_id_like or delete_lists_by_id_like.

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?

No when-to-use advice or alternatives are provided. The description simply restates the endpoint and parameters, leaving the agent to infer when this user-scoped like endpoint should be preferred over the many sibling list/like tools.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the write nature and idempotency. The description adds minimal behavioral context beyond 'reorder items' and the HTTP method; it does not describe effects on the list, potential errors, or side effects. With annotations covering safety, this is adequate but not rich.

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 concise, with the core purpose front-loaded ('Reorder items on a list') followed by the endpoint and parameter list. Every sentence serves a purpose, and there is no fluff. The structure is efficient for quick scanning.

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?

With 3 required params, an open body object, and no schema descriptions, the description does not provide enough context for a successful call. It relies on external hints ('Read the matching GET or /schema') rather than explaining the payload structure or reordering semantics. The presence of an output schema reduces the need to explain return values, but the request side is still under-specified.

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 0%, so the description must compensate. It explains 'id' as 'the slug that identifies the user' (helpful), but 'list_id' is only called a 'Path parameter' with no format details, and 'body' is forwarded to the schema without any field hints. Given the schema has no descriptions and body is an open object, this is insufficient for an agent to construct a correct request without external lookups.

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 clearly states 'Reorder items on a list' and provides the HTTP method and endpoint, giving a specific verb and resource. However, it does not explicitly distinguish from sibling reorder tools like create_users_by_id_lists_by_list_id_items_reorder or create_sync_watchlist_reorder, which may cause 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 gives the HTTP method and indicates to read the GET or /schema for body fields, but it does not explain when to use this tool versus alternative reorder tools (e.g., create_users_by_id_lists_reorder, create_sync_favorites_reorder). No explicit conditions or exclusions are provided, leaving the agent to infer appropriate usage.

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

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

The annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds no behavioral context on top of that. It does not mention what reporting does, any side effects, authorization requirements, or idempotency implications. No contradiction with annotations, but no additional transparency either.

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 short and well-structured, with the action front-loaded and an Args section for parameters. It includes only the endpoint and essential argument guidance, with no filler. The newline-separated structure is easy to scan.

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?

The description leaves out the core semantics of what 'report' actually does, how it differs from other report endpoints, and any prerequisites or expected behavior. It does point to external schema discovery for the body, but that is a workaround rather than complete documentation, making this insufficient for an agent to confidently invoke the tool.

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 0%, so the description must compensate. It does explain 'id' as a slug or 'me', and it tells the caller to check the matching GET or /schema endpoint for body fields, but 'list_id' is only described as 'Path parameter' and the body remains undocumented. Partial compensation, but limited.

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 specific verb and resource: 'Report a user's list.' It also includes the endpoint path, which identifies the target resource clearly. However, 'report' is ambiguous (abuse report vs. generated report), and it does not distinguish this from sibling report tools like create_lists_by_id_report.

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?

There is no guidance on when to use this tool versus alternatives such as create_lists_by_id_report or the GET tool for the same list. The description only states what the operation does, with no conditions, exclusions, or reference to sibling behavior.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the endpoint and advises reading the matching GET or /schema endpoint, which is mildly useful, but it does not disclose behavioral details such as side effects or ordering semantics beyond the word 'Reorder'. No contradiction with annotations.

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 short, front-loaded with the core operation, and contains no filler. The Args section adds path/body distinction and a practical pointer for field discovery, though it partially duplicates schema property titles.

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?

Given the output schema and annotations, the description covers the basic call mechanics and even offers a strategy for the unknown body shape. However, it leaves the distinction from the very similar sibling reorder tool unstated, and the actual body semantics are deferred to external endpoints rather than summarized.

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?

With 0% schema description coverage, the description must compensate. It clarifies that id is a path parameter and body is the request payload, and it directs the agent to read the matching GET or /schema endpoint to discover the expected fields. This is helpful but stops short of specifying what the body should actually contain.

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 starts with 'Reorder a user's lists', a clear verb+resource statement that explains the operation. It is distinct from the close sibling create_users_by_id_lists_by_list_id_reorder by referring to 'a user's lists' rather than a specific list, but it does not explicitly call out that difference.

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?

No guidance is given about when to use this tool versus alternatives such as create_users_by_id_lists_by_list_id_reorder or other reorder endpoints. The description only states what the tool does, not the conditions that select it or exclusions for other tools.

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