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

Annotations already declare readOnlyHint=true, so the description does not need to repeat that. It adds a small behavioral detail about consistency with external sites, but no deeper context like permissions or side effects. This is acceptable but not exceptional.

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 sentences with the primary action stated first. No filler. It is appropriately concise for such a simple tool.

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 zero-parameter, read-only list tool with no output schema, the description fully conveys what the response contains (IMDb ids). It is complete enough for an agent to understand the tool's purpose and expected return value.

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?

There are zero parameters, so the baseline is 4. The description does not need to compensate for schema gaps, and it correctly avoids inventing unnecessary parameter details.

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 uses a specific verb ('Lists') and a clear resource ('IMDb ids favorited in the put.io account config'). It also distinguishes from sibling favorites_update by focusing on listing rather than modifying.

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 clear context about what this tool does and even adds that it matches the list shown on showfeed.site and moviemagnet.site. It does not explicitly mention alternatives or exclusions, but the use case is obvious.

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, covering the mutation and retry safety. The description adds context that the favorites list is stored in the put.io account config, which is useful but does not disclose additional behavioral traits such as error handling or 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 a single sentence that is front-loaded with the main action and resource. It is concise, clear, and contains no unnecessary words 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?

Given the tool's simplicity, full schema coverage, and annotations, the description is quite complete. It explains the modification target and storage location. It does not mention specific error behavior or duplicate handling, but these are not essential given the idempotentHint annotation.

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 provides complete descriptions for both parameters (imdbId and action), covering 100% of the schema. The description only restates the action types and resource, adding minimal semantic value beyond the 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 clearly states the action ('Adds or removes') and the resource ('IMDb id from the favorites list stored in the put.io account config'). It effectively distinguishes itself from sibling tools such as favorites_list by indicating a mutation operation rather than a listing operation.

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 explicit guidance on when to use this tool versus alternatives. It does not mention that favorites_list should be used for viewing, nor any preconditions or context for adding/removing favorites. Usage is implied only by the tool name and verb.

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=true, and the description adds valuable behavioral context: results are magnet links sorted by seeder count, and sign-in is required. No contradiction with annotations; the additional details exceed what structural fields convey.

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 sentences, no fluff. The first sentence front-loads the primary action and output, and the second covers the prerequisite and downstream call. Every word 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 covers the main behavior, output format, sorting, sign-in requirement, and suggested next step. With no output schema, this is sufficient for a read-only search tool; minor gaps like default limit and error handling are covered by the schema or are not critical.

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

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

Schema description coverage is 100% for all 5 parameters, so the description need not reiterate parameter details. It only mentions IMDb id, which is already documented in the schema. As no extra parameter semantics are added, baseline 3 is appropriate.

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?

Description states it searches torrent indexers for a movie by IMDb id and returns magnet links sorted by seeder count. This clearly identifies the tool's purpose and distinguishes it from sibling tools like shows_find_torrents and putio_add_transfer.

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 specifies a prerequisite (requires put.io sign-in) and a follow-up workflow (pass magnet to putio_add_transfer). While it doesn't explicitly contrast with alternative tools, the movie-focused IMDb-id search makes the intended use clear.

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=true, so the read-only nature is covered. The description adds useful behavioral context beyond annotations: 'No sign-in required' and 'from moviemagnet.site,' which indicates the data source. This is valuable context for the agent regarding auth and provenance, though it doesn't describe response format or error behavior.

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

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

The description is a single sentence, front-loaded with the action ('Fetches full details'), and every word contributes meaning. It's appropriately succinct with 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 simple single-parameter read operation with annotations covering safety, the description covers the essential context: source, auth requirement, and scope (single movie by ID). It doesn't explain return values, but no output schema exists, and the tool's simplicity makes this acceptable. Sibling tools clarify domain boundaries.

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 a 100% description of the sole parameter (imdbId: 'IMDb id, e.g. tt0083658'), so the description doesn't need to add parameter details. The tool description reinforces 'by IMDb id' but adds no new semantics beyond the schema, which matches the baseline for high 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 the tool's purpose: 'Fetches full details for a single movie by IMDb id.' It specifies the resource (movie), the operation (fetch), and the identifier (IMDb id), which distinguishes it from sibling tools like movies_search (search across movies) and movies_popular (list popular movies).

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: when you have a known IMDb ID and need details for a single movie. It also notes 'No sign-in required,' indicating no authentication is needed. However, it does not explicitly mention alternatives or exclusions, such as recommending movies_search when you don't have an ID, so it falls short of the highest bar.

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=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the data is based on recent view counts and requires no authentication, which is valuable for an agent deciding whether to invoke this tool.

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 one sentence, front-loaded with the purpose ('Returns...'), and includes only the essential added detail ('No sign-in required'). Every word contributes value.

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 no-parameter, read-only list tool with no output schema, the description sufficiently conveys what is returned and the access requirement. The tool is simple and the description covers the core aspects an agent needs to know.

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?

There are zero parameters, and the input schema is empty, so the description does not need to explain parameter semantics. The baseline for a no-parameter tool is 4, and the description adds the relevant note about not requiring sign-in, which is a form of access semantics rather than parameter 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 uses a specific verb ('Returns') and resource ('the movies most viewed on moviemagnet.site recently'), which clearly identifies what the tool does. It also distinguishes from siblings like movies_search and movies_get by highlighting the 'most viewed' and 'recently' criteria.

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 clear context by stating it returns recently viewed movies and explicitly notes 'No sign-in required'. It does not explicitly exclude alternatives, but for a simple list endpoint the usage context is clear enough.

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=true and openWorldHint=true, and the description adds useful context: it searches an external site (moviemagnet.site), requires no authentication, and returns IMDb ids. While it doesn't discuss pagination or error behavior, the added detail about return format and auth goes beyond the bare 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 two short sentences that are front-loaded with the core purpose, then provide immediate follow-up usage. Every word earns its place, with no filler or redundant repetition of the tool name or title.

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 one-parameter search tool with no output schema, this description is complete: it states the input (title), the output (IMDb ids), the destination (moviemagnet.site), and the integration with sibling tools. The annotations cover safety and open-world behavior, so nothing critical is missing.

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 already provides 100% coverage with a clear description for the single 'query' parameter, including an example. The tool description's mention of 'by title' aligns with the schema but adds no new semantic detail beyond what the parameter description already provides, so the baseline of 3 is appropriate.

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 uses a specific verb+resource combination ('Searches moviemagnet.site for movies by title') and clearly distinguishes this tool from siblings like movies_get and movies_find_torrents by stating that it returns IMDb ids to pass to those tools. This makes its role 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 clearly implies when to use this tool (search by title before calling movies_get or movies_find_torrents) and states that no sign-in is required. It does not explicitly list exclusions or alternative search tools, but the intended workflow is clear from the mention of downstream 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 and openWorldHint, so the description adds the signed-in context and specific return fields (username, disk space). This goes beyond annotations without contradicting them, providing useful 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?

A single concise sentence front-loads the verb and states the two key return values. Every word earns its place with no unnecessary detail.

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 zero-parameter read-only tool, the description fully explains what it returns. Since no output schema exists, the explicit mention of username and disk space satisfies completeness.

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 has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter detail, but none is needed given the empty 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 clearly states the tool 'Returns the signed-in put.io username and remaining disk space,' with a specific verb and resource. This distinguishes it from sibling tools like putio_auth_status or putio_login.

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 such as putio_auth_status or putio_login. The description implies a signed-in context but does not explicitly contrast with other account-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?

Beyond annotations (readOnlyHint=false, etc.), the description adds critical side effects: 'spends the account's bandwidth and storage' and requires user confirmation. This is valuable context not inferable from annotations alone.

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 sentences deliver the action, typical use, cost, and confirmation requirement without redundancy. Well-structured and 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?

Covers the core behavior, use case, and important cautions. With a 3-param schema and no output schema, the description is sufficient, though it doesn't mention progress tracking or cancellation alternatives.

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 descriptions already cover all parameters (100% coverage), including the meaning of url, confirm, and saveParentId. The description does not add new parameter-level details beyond what's in the 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 clearly states 'Starts a download on put.io from a magnet link or HTTP URL' with a specific verb and resource. It also mentions typical sources (movies_find_torrents, shows_find_torrents), distinguishing it from sibling putio management 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?

Provides context that this tool is typically used after torrent searches from movies_find_torrents or shows_find_torrents, and instructs to confirm with the user first. It does not explicitly list alternatives or when not to use it, but the use case is clear.

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=true and openWorldHint=true, lowering the burden. The description adds behavior beyond annotations: it tells that a token may be stored and that sign-in progress is tracked. No contradictions.

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

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

The description is a single, well-structured sentence that front-loads the action and includes the key concept of sign-in progress. No unnecessary words.

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 simple nature (0 params, no output schema), the description adequately explains what it reports (token validity and sign-in progress). It could specify the exact return format, but for a status checker this is 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 tool has zero parameters, so the baseline is 4. The description correctly avoids parameter details and focuses on the tool's purpose, which is sufficient.

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?

Description uses a specific verb ('Reports') with a clear resource (put.io auth status). It distinguishes from sibling tools like putio_login and putio_logout by focusing on token storage and sign-in progress.

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

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

The description implies usage context by referencing putio_login, indicating this tool checks the outcome of a sign-in. It provides clear context but does not explicitly state when not to use it or list 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?

Beyond the annotations (destructive, non-readonly, idempotent), the description adds crucial behavioral details: it distinguishes between stopping seeding and removing an entry based on state, and explicitly states that downloaded files are not deleted. This gives the agent a clear understanding of the side effects without relying solely on 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 three short, purposeful sentences. It is front-loaded with the core action, then explains conditional behavior, and ends with a key non-effect. No words are wasted.

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

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

For a simple tool with one parameter, no output schema, and annotations already covering safety, the description is complete. It explains what happens to seeding transfers, non-seeding transfers, and explicitly clarifies that files are not deleted. Nothing relevant is missing.

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 already covers 100% of the parameters, including a description for 'transferIds' ('Transfer ids to cancel'). The tool description only says 'by id', which adds no new information beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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 ('Cancels or removes transfers by id') with a specific verb and resource. It also differentiates the behavior between seeding and non-seeding transfers, distinguishing it from sibling tools like putio_clean_transfers. This is specific 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?

The description provides clear context on when to use this tool: when you have specific transfer IDs and want to cancel or remove them. It also gives an important exclusion ('Downloaded files are not deleted') which guides expectations. However, it does not explicitly mention alternatives or contrast with siblings like putio_clean_transfers, so it stops short of a 5.

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 destructiveHint=true and idempotentHint=true, but the description adds valuable context by clarifying 'Downloaded files are not deleted', which directly addresses a common concern. It also specifies 'all' transfers, indicating broad scope. This goes beyond the annotations without contradicting 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?

Two sentences, both essential. The first sentence states the core action, and the second adds a critical caveat about files not being deleted. No wasted words, and the structure is front-loaded with the primary verb.

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 zero-parameter, no-output-schema tool, the description fully explains the behavior and a key edge case. Combined with rich annotations (destructive, idempotent) and clear sibling context, the description is complet for an agent to invoke 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 tool has zero parameters, so the baseline is 4. The description correctly focuses on behavior rather than parameters, as there is nothing to explain. No parameter information is needed.

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

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

The description states a specific verb ('removes') and resource ('completed transfer entries from the transfer list'), clearly distinguishing it from sibling tools like putio_cancel_transfers (which cancels transfers) and putio_list_transfers (which lists them). The scope is precise: 'all completed' entries, and the title reinforces 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 implies its use case (cleaning up completed transfers) but does not explicitly contrast it with alternatives or provide when-not-to-use guidance. Sibling tools like putio_cancel_transfers are mentioned in the context, but the description itself does not direct the agent to prefer this tool for completed entries or avoid it for active ones.

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=true, so the read-only nature is known. The description adds the 'up-to-date' aspect and the download-progress use case, but does not disclose return format or potential caveats. With annotations covering safety, this is acceptable but not extensive.

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?

One concise sentence, front-loaded with the action and resource, and zero wasted words. It immediately communicates the tool's purpose and use case.

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 single-transfer read operation with annotations and a described parameter, the description is sufficient. It could mention what fields are returned, but the use case (progress) implies the payload. Given the tool's simplicity, it's adequately complete.

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 100%; the transferId parameter has a clear description referencing where to obtain it. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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 tool fetches details for a single transfer, with a specific use case of checking download progress. This distinguishes it from siblings like putio_list_transfers, which lists all transfers.

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 use when needing up-to-date details for one specific transfer, but does not explicitly name alternatives or state when not to use. The 'single transfer' and 'up-to-date' wording provides clear context among sibling 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 declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the folder-browsing behavior but does not disclose details like pagination, response structure, or potential variability. With annotations in place, 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 a single, tightly worded sentence: 'Lists files and folders in the put.io account. Pass a folder id to browse into it.' Every phrase earns its place; there is no fluff 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 read-only tool with one optional parameter and no output schema, the description is complete enough. It explains the main behavior and parameter usage. It does not detail the returned items' format, but that is not required given the tool's simplicity and the absence of an output schema.

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 already describes parentId ('Folder id. 0 is the account root.'). The tool description's statement 'Pass a folder id to browse into it' adds contextual meaning but does not introduce new information beyond the schema's description. With 100% schema coverage, a baseline of 3 is appropriate.

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 tool's function: 'Lists files and folders in the put.io account'—a specific verb and resource. It also distinguishes from siblings like putio_list_transfers by focusing on files/folders rather than transfers.

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 clear usage context by explaining how to browse into folders: 'Pass a folder id to browse into it.' It does not explicitly name alternatives or exclusions, but the scope is obvious enough for a simple list 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 declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds a small extra detail ('with download progress') that hints at output content, but does not disclose additional behavioral traits such as pagination, response size limits, or how 'current' vs 'recent' is determined. This is consistent with annotations and adds some value beyond 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 a single sentence of 14 words, front-loaded with the core action and resource. It wastes no words and is immediately informative, earning a high score for efficiency and clarity.

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 low-complexity list tool with two optional parameters and no output schema, the description is largely complete: it states the resource, scope, and an output feature. It doesn't explain return structure, but that's not required given the absence of an output schema. The annotation-driven safety profile is well covered; the only missing element is explicit guidance on how 'current' and 'recent' are separated, but this is not critical for 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 input schema fully documents both parameters (limit and status) with descriptions and constraints, providing 100% coverage. The description does not mention parameters directly, so it adds no extra semantic value over the schema. The baseline of 3 applies because the schema carries the meaning.

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 uses the specific verb 'Lists' with a clear resource ('transfers on the signed-in put.io account'), distinguishing it from siblings like putio_get_transfer (which fetches a single transfer) and putio_add_transfer (which creates transfers). It also adds scope ('current and recent') and output detail ('with download progress'), making the tool's purpose 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 implicitly conveys when to use the tool (to view transfers and their progress) but does not explicitly contrast it with alternatives like putio_get_transfer for a single transfer or putio_clean_transfers for cleanup. No exclusions or 'use instead' guidance is provided, so the usage context is clear but not fully elaborated.

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 meaningful behavioral context beyond the annotations: it is an async browser-based flow, needs user interaction, and requires a follow-up status check. This complements readOnlyHint=false and openWorldHint=true. It does not mention token overwriting, but that is a minor omission.

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 two concise sentences. The first states the primary function, the second provides follow-up and prerequisite guidance. Every phrase earns its place with no 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 login tool with one optional param and no output schema, the description is fully complete: it covers purpose, the interactive browser nature, the follow-up status check, and the dependency on this tool for other actions. The agent has all necessary 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 100% for the single 'force' parameter, so the schema already provides clear meaning. The tool description adds no additional parameter context, matching the baseline for fully self-documenting 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 clearly states the tool 'Starts the put.io sign-in flow' and that it returns browser instructions for the user. This specific verb+resource phrasing, combined with the mention of a follow-up status check, distinguishes it from sibling tools like putio_auth_status and putio_logout.

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?

Explicit usage context is provided: 'Required before searching torrents or creating transfers' and 'Call putio_auth_status afterwards to confirm completion.' This gives clear when-to-use instructions and defines the expected workflow relative to sibling 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 indicate destructiveHint=true, but the description adds value by specifying exactly what is deleted (the stored token) and where (OS keychain or credential file), which clarifies the scope of destruction. This goes beyond the annotation's generic destructive flag.

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

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

The description is a single concise sentence that is front-loaded with the action ('Deletes the stored put.io token') and includes only essential detail. No redundant words or clutter.

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 no-parameter, no-output-schema tool, the description is complete. It clearly defines the action, the affected resource, and the storage location, leaving no ambiguity about what the tool does.

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 has zero parameters, so the description does not need to explain parameter details. The baseline for no parameters is 4, and the description appropriately focuses on the action rather than non-existent inputs.

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 tool deletes the stored put.io token from the OS keychain or credential file, which is a specific verb and resource. It distinguishes itself from siblings like putio_login and putio_auth_status by describing the logout action explicitly.

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 title 'Sign out of put.io' and description provide clear context for when to use this tool: to end a put.io session by clearing stored credentials. It does not explicitly mention alternatives or exclusions, but the use case is unambiguous and not misleading.

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=true and openWorldHint=true, so the safety profile is established. The description adds valuable behavioral details: it returns magnet links sorted by seeder count and requires authentication. This goes beyond the annotations without contradicting 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?

Two sentences, front-loaded with the primary action, then a usage tip and a prerequisite. Every sentence earns its place with no repetition of schema metadata.

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 lacking an output schema, the description states the return type (magnet links), sorting (by seeder count), and input requirements (IMDb id, optional filters). It does not detail error handling or result format beyond this, but for a search tool with rich schema coverage it is sufficiently complete.

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 100%, so the baseline is 3. The description adds semantic meaning by explaining that season/episode filtering targets a single airing, which clarifies the intent behind those parameters. It also frames the output as sorted by seeder count, giving context to minSeeders.

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 a specific verb ('Searches torrent indexers') and identifies the resource (a show by IMDb id). It clearly distinguishes itself from sibling tools like movies_find_torrents by specifying TV shows, and from shows_search by stating it returns magnet links rather than metadata.

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 concrete usage example ('Filter to a specific season and episode to find a single airing') and a prerequisite ('Requires a put.io sign-in'). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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?

Beyond annotations (readOnlyHint, openWorldHint), the description adds 'No sign-in required' and explicitly mentions the inclusion of the full episode list, providing nontrivial behavioral context. It doesn't cover return format or error cases, but the annotations already indicate a safe read 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?

The description is two sentences, front-loaded with the primary purpose, and the second sentence adds a concise auth note. There are no redundant or unnecessary words.

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, good annotations, and complete parameter schema, the description adequately covers the primary purpose, auth, and episode list inclusion. Since there is no output schema, a bit more detail on return shape could help, but the current description is sufficient for a straightforward read-only fetch.

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?

All three parameters (imdbId, season, includeEpisodes) are fully described in the input schema, and the description adds no additional meaning or examples. Thus the baseline score of 3 applies.

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 uses the specific verb 'Fetches' with a clear resource: 'details for a single show by IMDb id'. It explicitly distinguishes this tool from siblings like shows_search and shows_popular by emphasizing the single-show lookup and the inclusion of the full episode list.

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?

Clear context is provided that this tool is for fetching details for a specific show when you have its IMDb id. While it doesn't explicitly name alternatives or exclusions, the 'by IMDb id' phrasing makes the intended use obvious.

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=true and openWorldHint=true, and the description adds valuable context by stating the data source ('showfeed.site'), the recency qualifier ('recently'), and the lack of authentication requirement. This goes beyond the annotations without contradicting 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 a single, clear sentence that front-loads the action and includes only essential information. Every word contributes meaning, with no redundancy or 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 simple, parameterless list tool, the description covers the key aspects: what data is returned (popular shows), the source, recency, and auth requirements. While the exact return format isn't described, the annotations and simplicity of the tool reduce the need for additional detail.

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 has zero parameters, so the schema fully covers everything. The baseline for zero params is 4, and the description doesn't need to add parameter-related details beyond confirming no inputs are required.

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 tool returns the most viewed shows on showfeed.site recently, using a specific verb ('Returns') and resource ('shows most viewed'). This distinguishes it from sibling tools like shows_search and shows_get, which focus on searching or fetching specific show details.

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 clear context by noting it returns recently popular shows and that no sign-in is required, which is essential for an agent deciding whether to invoke it. While it doesn't explicitly name alternatives, the zero-parameter nature and clear scope make the intended use obvious.

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=true and openWorldHint=true, so the safe read-only nature is covered. The description adds value beyond annotations by specifying 'No sign-in required' and clarifying the output (IMDb ids). This is useful behavioral context, though it does not detail edge cases or rate limits.

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

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

The description is two concise sentences, front-loaded with the primary action, and every word adds value. No fluff 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?

Given the tool's simplicity (one parameter, no output schema) and the presence of annotations, the description covers the essential context: source (showfeed.site), input (title), output (IMDb ids), downstream usage, and auth requirement. This is complete for the tool's 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?

Schema description coverage is 100%, with the query parameter fully documented including an example. The description itself does not add additional meaning beyond the schema, so the baseline of 3 is appropriate.

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 ('Searches showfeed.site for TV shows by title') with a clear resource and scope. It also distinguishes from sibling tools by mentioning the output ('IMDb ids') and downstream tools ('shows_get or shows_find_torrents'), and the title 'Search TV shows' separates it from movies_search.

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 indicates the intended workflow by stating that returned IMDb ids should be passed to shows_get or shows_find_torrents, which provides clear context for when to use this tool. However, it does not explicitly mention when not to use it or name alternatives like movies_search, so it falls short of a 5.

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