mcp-server

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description reinforces the non-idempotent, creates-a-new-job semantics ('Start a NEW ... job', 'creates a job and begins processing'). It also discloses the return contract (job ID / mediaId) despite the absence of an output schema, though it says nothing about quotas, auth requirements, or failure modes for inaccessible URLs.

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

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

Three sentences, each earning its place: the core action and inputs first, the disambiguating exclusion second, and the return value last. 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?

With no output schema, the description supplies the missing return contract (job ID used to track processing), and it names the follow-up tools conceptually. Combined with full parameter coverage and annotations, an agent has everything needed to call it 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 both url and mediaType are already documented, including the accepted URL forms and the enum values. The description's media-type list largely restates the enum rather than adding syntax or constraints beyond the schema, so the baseline 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?

States a specific verb+resource ('Start a NEW Echosaw analysis job from a ... URL') and explicitly names the sibling it is not ('it does not fetch previously analyzed media — use echosaw_download_media'). An agent can distinguish it from echosaw_download_media and echosaw_get_analysis_results without opening any schema.

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?

Gives the use condition (start processing from a public or platform URL) and an explicit exclusion with the alternative tool for the confusable case (retrieving already-analyzed media). It also enumerates acceptable input categories, so the agent knows when this tool applies.

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, non-destructive, and openWorld safety profile. The description adds meaningful context beyond that: the retrieval methodology (RAG over transcripts/summaries/spoken passages) and the return content (answer plus source media), plus the stateful follow-up behavior implied by conversationId.

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

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

Three sentences, front-loaded with the core purpose, followed by the sibling routing rule and optional-parameter guidance. No filler; every sentence adds actionable 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 present, the description carries the return-value burden and does so ('Returns the answer plus the source media it drew from'). Along with the RAG source description and routing guidance, an agent has everything needed to invoke it 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 each parameter is already documented, and the description's mentions of mediaIds and conversationId largely restate the schema. Baseline 3 is appropriate since 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?

States a specific verb+resource: asking a natural-language question and getting a synthesized answer grounded in analyzed media, with the RAG mechanism named (transcripts, summaries, spoken passages). It explicitly distinguishes itself from sibling echosaw_search_media by contrasting 'answer' vs 'ranked 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?

Gives an explicit when-to-use condition ('when you want an answer rather than a ranked list') and names the alternative tool (echosaw_search_media) with its condition. It also clarifies optional usage: mediaIds to restrict scope, conversationId to continue a prior exchange.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely non-obvious context: the shape of returned fields, that matchReasons explain matches, and critically that 'Lower score is a closer match' — an inverted-scoring convention that would otherwise trip an agent. It stops short of mentioning result limits or pagination.

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?

Front-loaded with the core verb+resource and the tool-routing sentence is placed last where it belongs. Slightly dense with parentheticals ('60-second transcript windows', field enumeration), but nearly every clause 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?

There is no output schema, and the description compensates by enumerating return fields (titles, summaries, transcript snippets, labels, relevance scores) plus the conditional timestampSec/matchReasons behavior. Combined with the routing guidance, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and both enums (scope, mediaType) are fully documented in the schema, so the schema does the heavy lifting. The description adds only incidental context about transcript windowing and does not extend the meaning of any parameter. 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?

States a specific verb (semantic search) and resource (analyzed media library), and narrows scope to spoken transcript windows plus visual frames/clips. It also explicitly names the sibling it is not (echosaw_ask_media), so an agent can distinguish it from the other search-adjacent tool without opening a schema.

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?

Gives direct usage guidance ('Use this to find previously analyzed media by topic, content, keyword, or a phrase someone said') and names the alternative with the exact condition that selects it ('To get a synthesized answer instead of a result list, use echosaw_ask_media'). Nothing is left to inference.

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.