mcp-server

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

Annotations already indicate the tool is not read-only and not idempotent. The description adds valuable behavioral context: it creates a new job, begins processing, represents an entry point, and does not retrieve prior analyses. This goes beyond the annotations without contradicting them, though it does not detail asynchronous behavior or potential external 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 three sentences, each earning its place: the first states the primary action, the second clarifies scope and exclusion, and the third explains the return value. It is front-loaded with the main purpose and contains no redundant 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?

With no output schema, the description correctly explains the return value (job ID / mediaId) and its role in tracking and retrieving results. The tool is simple (2 parameters) and the description covers the full workflow, including when not to use it, so the context is 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 baseline is 3. The description adds meaning by specifying 'publicly accessible media URL' and giving examples of video platforms (YouTube, Rumble, Vimeo), which is a constraint not explicitly in the schema. This strengthens parameter understanding beyond the enum and URL description.

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+resource: 'Start a NEW Echosaw analysis job', clearly indicating the tool creates a job. It further distinguishes this from 'fetch previously analyzed media' and explicitly names echosaw_download_media as the alternative, making the purpose distinct among siblings.

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 explicit usage context: it is an 'entry point' for new jobs, and it explicitly excludes fetching existing media by pointing to 'use echosaw_download_media for that'. It also explains what the caller receives (mediaId) and how it is used, giving clear when-to-use 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 discloses the server-side long-polling mechanism and the 25-second hold, which goes beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It adds useful behavioral context about how the tool operates, though it doesn't mention timeout handling or possible failure modes.

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

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

The description is concise and well-structured: two sentences that immediately state purpose, explain the polling behavior, and give a clear usage directive. Every sentence earns its place with no wasted 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?

For a low-complexity tool with one parameter and no output schema, the description covers purpose, behavior, and usage sufficiently. It is complete enough for an agent to select and invoke it correctly, though it doesn't explicitly describe return values (no output schema to reference).

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% with the single parameter mediaId fully described in the input schema. The description adds no additional semantic detail about the parameter beyond referencing that it is the mediaId returned by echosaw_analyze_media_url, which is already in the schema. 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?

The description clearly states the tool's purpose: 'Retrieve the current processing state of an Echosaw analysis job.' It uses a specific verb ('retrieve') and resource ('processing state of an Echosaw analysis job'), which distinguishes it from sibling tools like echosaw_get_analysis_results that likely fetch final results.

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 explicit usage guidance: it explains the long-polling behavior (holds connection up to 25 seconds) and instructs 'Call once and wait for the response,' explicitly advising against repeated polling. It doesn't name a specific alternative tool, but the guidance is practical and 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 mark this as a write operation (readOnlyHint=false), so the description adds value by disclosing that folders can be nested and by giving a concrete example. It doesn't discuss failure modes or permissions, but for a simple create tool this is adequate.

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 core action, and the example is both illustrative and compact. 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?

For a straightforward folder creation tool with 2 parameters and no output schema, the description is sufficient. It explains the purpose, nesting capability, and provides an example. It doesn't cover edge cases (e.g., duplicate names), but those aren't critical for basic usage.

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's example reinforces how parentPath is used but doesn't add substantively new parameter semantics beyond what the schema already provides.

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 ('Create') and resource ('folder in your media library'), clearly distinguishing it from sibling tools like delete_folder, rename_folder, and list_folders. It also includes an example of nesting, leaving no ambiguity about the 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 gives context ('for organizing analyzed media') and demonstrates a nesting use case ('Q1 2026' inside '/Marketing'), which implies when to use it. It does not explicitly exclude alternatives, but the create intent is obvious given the sibling set.

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 flag this as destructive and non-read-only, but the description adds valuable behavioral detail: items are moved to the parent folder by default. This goes beyond what annotations provide and helps the agent understand the side effects. No contradictions 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 two sentences, front-loaded with the primary action, and includes a key constraint. Every sentence earns its place with no filler. Under 50 words, it is highly 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?

For a delete tool with no output schema, the description covers the essential behavioral aspects: what happens to items (moved by default) and a critical restriction (no root deletion). Combined with the annotations declaring destructive intent and idempotency, the tool is fully specified 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?

Schema coverage is 100%, so both parameters are already well documented in the schema. The description only restates the default behavior of 'moveItemsToParent' ('by default'), adding no new semantic information beyond what the schema provides. 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?

The description clearly states the tool's function: 'Delete a folder from your media library.' This is a specific verb+resource that distinctly separates it from sibling tools like create_folder, rename_folder, and list_folders. The added constraint about the root folder further clarifies scope.

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 for when to use the tool—when deleting a folder. It also includes an important exclusion ('Cannot delete the root folder'), though it does not explicitly discuss alternatives or when not to use it beyond the root restriction. This is sufficient for a straightforward delete 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it generates a presigned download URL, the URL is valid for 1 hour, and it only fetches existing media. 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?

Every sentence earns its place: first sentence states what it does, second clarifies limitations and names an alternative, third gives a critical detail (URL expiry). No filler, well 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?

For a simple tool with one parameter, rich annotations, and no output schema, the description is complete. It covers the purpose, key side effects (presigned URL, expiration), and what it does not do. No important gaps remain.

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 describes the single parameter (mediaId) with a clear description, and schema coverage is 100%. The description reinforces the meaning by saying 'identified by mediaId' but provides no additional detail beyond the schema baseline.

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?

Uses a specific verb ('Retrieve') and clearly identifies the resource ('original source media file of an already-analyzed job' generated via presigned URL). It explicitly distinguishes itself from sibling tools by stating it does not upload or start analysis, and even names the alternative tool (echosaw_analyze_media_url).

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 explicit when-to-use guidance: for already-analyzed jobs and fetching existing media only. Clearly states what it does not do (upload or analyze) and names the alternative for those cases. This fully addresses when to choose this tool over 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 readOnly, idempotent, and non-destructive behavior. The description adds value by describing the content of results (summaries, transcripts, entities, events). It does not contradict annotations and provides context beyond the structured data.

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 sentence that front-loads the primary action and includes several relevant details without unnecessary verbosity. Every phrase 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?

No output schema exists, but the description gives a high-level overview of return types. It does not mention the full list of section options or the truncation behavior, but these are covered by the schema. Overall adequate for a retrieval tool with annotations.

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?

Input schema has 100% parameter description coverage, so the baseline is 3. The description does not add specific parameter details beyond what the schema already provides, such as the truncation behavior for 'section'.

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 clearly states the tool retrieves structured analysis results for a completed Echosaw job, listing example content. This distinguishes it from sibling tools like echosaw_check_job_status and echosaw_download_media.

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 phrase 'for a completed job' gives clear context on when to use the tool, implying the job must be finished first. However, it does not explicitly name alternatives or state when not to use it, such as checking status first.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavior by stating 'Returns null if you are not a member of any organization', which is not inferable from annotations and helps with edge-case 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 a single sentence of about 30 words. It front-loads the action and resource, then enumerates the returned fields. No filler or repetition; every word contributes to the tool's understanding.

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 no parameters and no output schema, the description is complete. It specifies what data is returned, includes the null-case behavior, and the annotations cover safety. No further details are necessary 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 tool has zero parameters, and the schema properties are empty. With 0 params, the baseline is 4, and the description correctly omits parameter details. There is nothing for the description to add beyond what the schema already conveys.

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 'Retrieve' as a specific verb and clearly identifies the resource: 'your Echosaw organization'. It lists the key fields returned (name, role, creation date, active member count), which distinguishes it from sibling tools like get_profile that target user-level data.

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: use this tool to obtain organization-level details. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous and the sibling tools serve distinct resources (e.g., profile, folders, media). The intended usage is evident without further 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=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the exact data returned (subscription tier, email, organization membership, free tier status) and the practical use case, which 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 two sentences with no wasted words. The first sentence states the action and outputs; the second provides the usage context. Every phrase earns its place, and the structure is front-loaded with the most important 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 no parameters, is annotated as read-only and idempotent, and has no output schema, the description fully covers what the tool does, what data it returns, and when to use it. There are no gaps in the provided information.

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 already documents everything. The baseline for 0 params is 4, and the description does not need to add parameter-level details. It correctly avoids inventing parameters.

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 'Retrieve' and clearly identifies the resource as 'your Echosaw account profile.' It enumerates the key data fields (subscription tier, email, organization membership, free tier status), which distinguishes it from sibling tools like echosaw_get_organization by focusing on the personal account rather than an organization.

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 explicitly states when to use the tool: 'Use this to understand your current plan limits and account details.' This provides clear context for usage, though it does not mention alternatives or exclusions. Since no closely related sibling tool exists, this is sufficient.

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 read-only, idempotent, and non-destructive behavior. The description adds return format ('folder structure with paths, display names, and item counts'), which is valuable given no output schema. It does not discuss auth or rate limits, but annotations cover the safety profile.

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, front-loaded with the action verb, and efficiently communicates purpose and return 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 simple list tool with one optional parameter and no output schema, the description plus annotations and schema are fully complete. It explains what is returned and the use case, so no additional detail is necessary.

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% for the single parameter parentPath, so the baseline is 3. The description does not add additional meaning about parameters, relying entirely on 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 'List folders in your media library' with a specific verb and resource, and adds return details about folder structure. This distinguishes it from siblings like list_media or create_folder.

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 a clear usage context with 'Use this to understand how your media is organized,' but does not explicitly mention alternatives or exclusions. It gives a clear purpose without naming 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, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: 'Returns up to 25 items by default' and lists server-side filters, which informs the agent about default limits and filtering capabilities. 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 two sentences, front-loaded with the core action and metadata. It efficiently covers purpose, default limit, use case, and filters without padding. 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 list tool with 6 parameters and no output schema, the description is quite complete: it states the returned metadata fields, default limit, filters, and use case. It could mention pagination or the folderPath default, but the schema covers those details. Overall, sufficient for safe 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 100%, with each parameter adequately described (e.g., 'Filter by job status'). The description adds minimal extra meaning—just grouping 'server-side filters' collectively. Since the schema already documents all parameters, the description provides no significant additional 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 clearly states the tool lists media items with metadata and mentions use cases ('browse your media library or find a specific mediaId'). It distinguishes from sibling echosaw_search_media by framing this as browsing rather than searching, but doesn't explicitly name or contrast alternatives, so it falls short of 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 gives clear usage context ('Use this to browse your media library or find a specific mediaId'), which helps the agent decide when to invoke it. However, it does not mention when not to use it or explicitly point to alternatives like echosaw_search_media, so it lacks full exclusion 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 readOnlyHint=false and destructiveHint=false, so it's clear this is a non-destructive write operation. The description adds little beyond stating it moves items, and does not disclose potential side effects (e.g., overwriting, folder existence 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 concise and front-loaded with the action. Both sentences earn their place: the first states the purpose, the second provides crucial input-finding guidance. 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?

Given the tool's simplicity and rich annotations, the description is mostly complete. It covers what, how, and where to find the parameters. It could mention whether the target folder must pre-exist, but the instruction to use list_folders implies it. No output schema exists, so missing return details are 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 coverage is 100%, so each parameter is well-defined. The description adds value by explaining how to obtain valid values (using list_media for mediaIds and list_folders for targetFolderPath), which goes beyond the schema's basic definitions.

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 ('Move one or more media items to a different folder') with a specific verb and resource. It distinguishes itself from sibling tools (list, create, delete, rename folders) by focusing on moving media items.

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 practical guidance on how to find the required inputs by directing users to echosaw_list_media and echosaw_list_folders. It implies when to use this tool (when moving media), but does not explicitly contrast with alternatives like 'when not to use'.

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 write operation (readOnlyHint=false), not destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds that the folder path updates to reflect the new name, which is helpful but not rich in side-effect detail (e.g., effects on permissions or child references). 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?

The description is two short, front-loaded sentences with no redundant or speculative content. Every word contributes to understanding the tool's purpose and effect.

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 rename operation with strong annotations and no output schema, the description covers the core action and outcome sufficiently. It specifies that the folder must exist and that the path updates, leaving no major gaps 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 schema provides 100% parameter coverage with clear descriptions for both folderPath and newName. The description's note that the path will update adds a relational nuance between the parameters but does not materially go beyond what the schema already communicates, so a 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?

The description clearly states 'Rename an existing folder in your media library' with a specific verb and resource, and the follow-up about the path updating distinguishes it from sibling folder tools. It unambiguously identifies this as the rename 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 phrase 'existing folder' implies the tool is for renaming folders that already exist, and the sibling list shows no other rename tool. However, there is no explicit guidance on when not to use it or alternatives (e.g., creating a folder instead), so the usage context is implied rather than 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 already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds useful return-format details (ranked results with titles, summaries, snippets, labels, relevance scores) and clarifies the semantic nature, which is valuable 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 filler. The first sentence states the core action, the second explains return values and usage. Everything 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 one-parameter read-only search tool with strong annotations, the description sufficiently covers what the tool does and what it returns. No output schema exists, so the explicit mention of result fields is helpful. It lacks only minor details like result limits or pagination, but those are not critical here.

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 a strong description for the 'query' parameter with examples and natural language guidance. The description adds 'by topic, content, or keyword' and 'semantic search', but these mostly reinforce the schema rather than introduce new meaning. 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?

The description clearly states a specific verb ('search') and resource ('analyzed media library'), and distinguishes from siblings like list_media by emphasizing semantic search and ranked results. It communicates the exact 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 phrase 'Use this to find previously analyzed media by topic, content, or keyword' provides clear context for when to invoke the tool. It does not explicitly mention alternatives or exclusions, but the sibling context 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?

Description adds significant behavioral context beyond annotations: conditions (COMPLETE analysis, ownership), moderation flag blocking, and that flags are returned in the response. This goes well beyond the readOnly/destructive/idempotent hints already provided.

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 main action, and every sentence adds necessary information without redundancy. No wasted 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?

For a simple toggle tool, the description covers the action, prerequisites, blocking conditions, and response content (flags). Combined with rich schema and annotations, this is fully sufficient for an agent to select and 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?

Schema description coverage is 100%, so the schema already documents both mediaId and isPublic. The description adds no extra parameter-specific meaning, only general context about moderation flags, which is not directly tied to 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 clearly states the tool's purpose: 'Toggle whether a media item is published to the Public Library.' This uses a specific verb+resource combination and differentiates it from sibling tools, none of which handle visibility toggling.

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 explicit prerequisites: 'Requires the analysis to be COMPLETE and the caller to own the item (or be an org member).' It does not explicitly name alternatives, but sibling tools do not overlap with this functionality, so the guidance is clear and sufficient.

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