mcp-server

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

The description adds valuable behavioral context beyond the annotations: it explains the asynchronous processing pattern, specifies that the URL must be publicly accessible or authorized (auth context), and clarifies the return value (job ID). Annotations indicate it's not read-only and not idempotent, but the description explains the actual user-facing behavior of the async job creation.

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 well-constructed sentences with zero redundancy. The first sentence front-loads the core action and constraint (URL submission without direct upload), while the second explains the return value and async tracking implication. 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?

Given the simple 2-parameter schema with complete coverage and existing annotations, the description successfully compensates for the missing output schema by explicitly stating what gets returned (job ID). It adequately explains the async workflow pattern, making it complete for this tool's complexity level.

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

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

With 100% schema coverage, the baseline is 3. The description adds semantic value by specifying that the URL must be 'publicly accessible or authorized'—critical authorization context not present in the schema's simple 'HTTP(S) URL' description. This helps the agent understand URL requirements beyond just the format.

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 specific action (submit URL for asynchronous analysis), the resource (media URL), and the mechanism (without uploading directly). It distinguishes this from direct upload methods and connects the output (job ID) to the tracking workflow, effectively differentiating it from siblings like get_analysis_results or check_job_status.

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 this tool (when you have a publicly accessible URL rather than a local file) and explains the async workflow requiring subsequent job tracking. However, it stops short of explicitly naming sibling tools like echosaw_check_job_status or echosaw_get_analysis_results as the specific next steps, though it implies the workflow.

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

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

Annotations cover safety profile (readOnlyHint, idempotentHint), but description adds crucial behavioral context: 25-second long-polling mechanism, connection holding behavior, and internal completion checking that isn't 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?

Three sentences structured perfectly: purpose statement first, technical implementation second, usage instruction third. Every sentence earns its place with zero 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?

Adequately covers the simple single-parameter operation. Explains return value concept ('processing state') despite lack of output schema. Could improve by mentioning possible status values (pending, completed, failed).

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 has 100% description coverage for the single mediaId parameter. Description does not add parameter-specific semantics beyond what the schema provides, meeting the baseline for high-coverage schemas.

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?

Clear specific verb ('Retrieve') + resource ('processing state of an Echosaw analysis job'). Effectively distinguishes from siblings like echosaw_analyze_media_url (which creates jobs) and echosaw_get_analysis_results (which retrieves final 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?

Provides explicit usage instruction ('Call once and wait for the response') and explains the long-polling mechanism to prevent incorrect polling loops. Lacks explicit comparison to sibling echosaw_get_analysis_results for when to use status vs results.

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 hints. The description adds valuable behavioral context not in annotations: the URL is 'presigned' (implementation mechanism) and has a strict 1-hour validity period (temporal constraint affecting agent 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 consists of two high-density sentences with zero waste. The first front-loads the action and resource, while the second provides the critical operational constraint (1-hour validity). 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 single-parameter tool with comprehensive annotations and schema coverage, the description adequately covers the essential operational quirks (URL expiry). It could be improved by explicitly stating the return value format (the URL string), though this is somewhat implied.

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

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

With 100% schema description coverage, the baseline is established. The description adds implicit semantic context that the mediaId refers to a completed job's source file, but does not significantly expand on parameter syntax or format 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 specific verbs ('Generate a presigned download URL') and clearly identifies the resource ('source media file'). It distinguishes from siblings like 'get_analysis_results' by specifying 'source media' versus processed results, and implies the prerequisite of a 'completed analysis job'.

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 restricting usage to 'completed analysis jobs,' indicating a prerequisite workflow. However, it does not explicitly contrast with siblings (e.g., when to use this versus 'get_analysis_results' for processed data versus source media).

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

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

Annotations cover safety profile (readOnly, idempotent, non-destructive). Description adds valuable content disclosure beyond annotations: enumerates specific output types (summaries, transcripts, entities, events) that define what 'analysis results' means, compensating for the missing output schema.

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?

Single dense sentence with zero waste. Front-loaded with action (Retrieve), followed by resource type, job state constraint, and content enumeration. Every clause provides distinct 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?

Appropriately complete for a 2-parameter read tool. With no output schema, the description's enumeration of return content types (summaries, transcripts, entities) is essential. Annotations handle behavioral hints, leaving description to cover domain-specific 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 has 100% coverage establishing baseline 3. Description adds semantic mapping by listing content types (summaries, transcripts) that correspond to the 'section' enum values, helping agents understand what each section contains without reading 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?

Excellent specificity with 'Retrieve structured analysis results' (verb + resource) and clear scope 'for a completed job'. Distinguishes from siblings like echosaw_download_media (raw files) and echosaw_check_job_status (job state) by emphasizing 'analysis results' containing intelligence outputs.

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?

Implies temporal prerequisite with 'completed job', indicating this should not be called on pending analyses. However, lacks explicit guidance to use echosaw_check_job_status first or contrast with echosaw_download_media for raw media vs structured data.

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

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

Annotations already establish read-only, idempotent, non-destructive nature. Description adds valuable context about specific data fields returned (subscription, trial status) and implies quota management relevance ('plan limits'), going beyond the structured 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 with zero waste. First sentence establishes scope and return payload; second sentence provides usage intent. Front-loaded with the most critical information (what it retrieves) before usage guidance.

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 comprehensively lists return fields (subscription tier, email, org membership, trial status) compensating for the missing structured output definition. Adequate for a simple, zero-parameter read operation.

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

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

Zero parameters present, meeting the baseline score of 4. Description appropriately focuses on return value semantics rather than inventing parameter documentation where none exists.

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?

Specific verb 'Retrieve' + specific resource 'Echosaw account profile' + explicit field enumeration (subscription tier, email, organization membership, trial status). Clearly distinguishes from media-focused siblings (analyze_media_url, download_media, etc.) by focusing on account metadata rather than content operations.

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 'Use this to...' guidance for understanding 'current plan limits and account details.' However, lacks explicit 'when not to use' or named alternatives, though the functional separation from media tools is obvious from sibling names.

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

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

Annotations cover safety profile (readOnly/idempotent), but description adds valuable behavioral context: specific metadata fields returned (filename, type, status, size, duration) and pagination behavior ('Returns up to 25 items by default'). 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?

Three efficient sentences with no waste. Front-loaded with action verb, followed by return details and usage context. 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?

Adequately compensates for missing output schema by listing returned metadata fields. Covers the single optional parameter's behavior. For a simple list operation with good annotations, this provides sufficient 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 has 100% description coverage for the 'limit' parameter. Description reinforces the default value (25) but doesn't add significant semantic meaning beyond what the schema already provides, warranting the baseline score.

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?

Clear verb ('List') and resource ('media items in your Echosaw library') with specific metadata fields listed. Deducting one point because it doesn't explicitly differentiate from sibling 'echosaw_search_media' for filtering use cases.

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

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

Provides implied usage ('Use this to browse your media library or find a specific mediaId') but lacks explicit when-not guidance or comparison to alternatives like 'echosaw_search_media' for complex queries.

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

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

Annotations cover safety profile (readOnly, non-destructive, idempotent). The description adds crucial behavioral context: it discloses the return structure ('titles, summaries, transcript snippets, labels, and relevance scores') compensating for the missing output schema, and clarifies the search methodology ('Semantic search' vs keyword matching).

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 tightly constructed sentences with zero redundancy. First sentence covers function and return values; second covers usage intent. Every clause provides distinct information not found in structured fields.

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

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

For a single-parameter read operation with rich annotations, the description is complete. It notably compensates for the absent output schema by detailing the five components returned in results, providing sufficient information for the agent to invoke the tool confidently.

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

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

While the schema has 100% coverage with examples, the description adds value by reinforcing the query semantics ('by topic, content, or keyword') and emphasizing the natural language/semantic nature of the search, helping the agent formulate appropriate queries beyond just the syntax shown in schema examples.

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 specific action ('Semantic search'), target resource ('analyzed media library'), and method. Clearly distinguishes from sibling 'echosaw_analyze_media_url' by emphasizing 'previously analyzed' content, and from 'echosaw_list_media' by specifying semantic/ranked retrieval rather than simple enumeration.

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 guidance ('Use this to find previously analyzed media by topic, content, or keyword') establishing when to use the tool. However, it does not explicitly contrast with 'echosaw_list_media' or 'echosaw_get_analysis_results' to clarify when those alternatives are preferable.

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