Social → Context

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

Annotations indicate idempotent and non-destructive behavior. Description adds the process context (browser login, token copy) and notes the difference between permanent and session configuration, which goes beyond annotations.

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

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

The description is succinct but packs essential information; it could be slightly more streamlined, but the front-loaded context is appropriate.

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

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

The description covers usage well but does not specify the return value or output format, leaving the agent uncertain about what to expect after calling with no token or with a token.

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

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

With 0% schema description coverage, the description fully compensates by explaining the sole parameter 'token' as a JWT and specifying its two usage modes: providing it for session login or omitting it to receive a link.

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 is for authentication, explaining the two-step process (browser login, copy token) and distinguishes it from unrelated sibling tools like 'connect' or 'marketplace'.

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?

Explicitly provides two usage paths: permanent by adding header to config, or session-only by pasting token. Also instructs when to call with a token vs without, guiding the agent on conditional invocation.

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, idempotentHint, and destructiveHint, so the description adds value by detailing the return structure (authenticated, pending, connect URLs) and conditional behavior. 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?

Two sentences efficiently convey the purpose and conditional behavior. No extraneous information; 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?

With no parameters and no output schema, the description fully explains what the tool returns in all cases. It covers both scenarios (all connected vs missing credentials) completely.

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?

No parameters exist (0 params, 100% schema coverage), so the baseline is 4. The description adds no parameter-specific information, which is appropriate given the absence of 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 clearly states the tool returns connection status and URLs, and provides specific details about output in two scenarios (all connected vs missing credentials). It distinguishes itself from siblings like 'authenticate' by focusing on status rather than performing authentication.

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

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

The description implies usage for checking connection status but does not explicitly state when to use it versus alternatives like 'authenticate'. However, with zero parameters and a simple purpose, the lack of explicit guidelines is acceptable but leaves room for improvement.

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 behavioral traits: writes require workspace owner/admin, search flags installed status, and list_tools/invoke work even in flat-mode clients. Annotations indicate readOnlyHint=false, so the description adds useful permission context without contradiction.

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

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

The description is lengthy but efficiently packs all essential information about multiple actions. It is front-loaded with the primary purpose and uses clear phrasing. Could benefit from bullet points or separation, but the continuous prose is acceptable given the complexity.

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 high parameter count (13) and no output schema, the description covers many scenarios (search, describe, install, etc.) and includes edge cases (list_tools after install). However, it omits details on return values and some parameter formats, leaving minor gaps.

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

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

Schema coverage is 0%, so the description must compensate. It explains the action enum and provides context for key parameters like query, mcp_id, and tool_id through action descriptions. However, many parameters (limit, arguments, conversation, etc.) are not explicitly explained, leaving gaps.

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 identifies the tool as 'THE official mcp.ai marketplace' for discovering and managing MCPs/tools. It explicitly states when to use it (FIRST for searches) and distinguishes it from external registries and sibling tools.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'use THIS tool (action=search) FIRST, before any external or generic MCP registry.' It also outlines specific actions and their contexts (e.g., list_tools after install).

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 (idempotentHint=true, destructiveHint=false, readOnlyHint=false) already indicate safe, idempotent behavior. The description adds the instruction to 'include the conversation array for reproduction', which is a useful behavioral detail. No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no unnecessary words. Each sentence adds 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 reporting tool with 3 parameters and no output schema, the description covers the main action but does not explain return values, side effects, or system response. This is acceptable but not fully 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?

With 0% schema description coverage, the description compensates partially by explaining the 'conversation' parameter's role ('recent messages for reproduction'). However, 'message' and 'context' are not elaborated, leaving gaps.

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 ('Report') and identifies the resources ('bug, missing feature, or send feedback'). It clearly distinguishes from sibling tools which are about authentication, download, and version info.

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

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

The description implies the tool is for reporting issues but does not provide explicit guidance on when to use it vs alternatives. Given the unrelated siblings, usage context is somewhat clear but lacks formal exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering its safety profile. The description adds only the scope (platform and adapter versions), which is helpful but not additional behavioral context.

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

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

Single sentence that is direct and front-loaded. Every word adds value with no redundancy.

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

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

Lacks details about the return format or structure, especially since there is no output schema. For a tool with no parameters, the description could hint at the response shape (e.g., 'returns a JSON object with version strings').

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?

No parameters are defined, so the description carries the full burden of meaning. It clarifies that the tool shows version info for platform and adapter, which is sufficient for an agent to understand its output.

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

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

Description states exactly what the tool does: 'Show the current MCP platform and adapter versions.' It uses specific verbs and resources, and clearly distinguishes from sibling tools like authenticate or connect, which serve different purposes.

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?

Context is clear: the tool is used to retrieve version information. No exclusions or alternatives are needed because it's a simple query; there is no other tool for this purpose among 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 indicate readOnlyHint=true and no destructive action. Description adds value by specifying it resolves to CDN URLs and returns all media qualities, with no transcription/vision. 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?

Three sentences, no wasted words. Front-loaded with action and output, followed by usage guidance and a clarifying exclusion. Perfectly succinct and structured.

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

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

Given the tool has only one required parameter and no output schema, the description adequately explains input, output (direct download URLs with quality labels), and constraints. No missing context for effective use.

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 0% description coverage, so description must explain the 'url' parameter. It clarifies acceptable URL types (TikTok/Instagram/YouTube links or direct .mp4/image URLs) and what the tool does with them, adding significant meaning.

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

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

The description clearly states it resolves TikTok/Instagram/YouTube links to direct download URLs with quality labels. It specifies supported platforms and output types, distinguishing itself from transcription tools.

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

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

Explicitly says 'Use when the user wants to DOWNLOAD/save the media instead of transcribing it.' Provides clear use case differentiation but does not compare to sibling tools like socialdl_extract or socialdl_metadata.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds context: downloading, processing, returning metadata, transcript, vision description; mentions YouTube uses existing captions. This supplements annotations well, though no mention of rate limits or error handling.

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

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

Description is a single paragraph with multiple sentences, each adding value: action, supported platforms, output details, YouTube caption behavior. No wasteful repetition. Could be slightly more structured (e.g., bullet points), but efficient overall.

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

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

Tool is complex (multiple platforms, output types: metadata, transcript, vision). No output schema. Description covers core functionality but lacks details on parameter usage, error scenarios, or output format. For a tool of this complexity, it is somewhat complete but has clear gaps in parameter documentation.

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

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

Schema description coverage is 0%, so description must compensate. It mentions 'social-media link' (url) implicitly, but does not explain 'language', 'transcribe', or 'describe_images' booleans. Only url context is provided, leaving 3 parameters undocumented. The description does not meet the burden for low-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?

Description clearly states it downloads social media links and returns text context (metadata, transcript, vision description). Lists specific platforms (TikTok, Instagram, YouTube, .mp4), making the action and scope very specific. Distinguishes from siblings like socialdl_download and socialdl_metadata.

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

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

Explicitly says 'Use this to give Claude the content of a video or post the user pasted,' which implies when to use. However, it does not mention when not to use or differentiate from sibling tools like socialdl_download or socialdl_metadata. No exclusion criteria or alternative recommendations.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that it is 'lightweight', does not transcribe/run vision, and is 'cheaper', providing behavioral context beyond annotations. Does not cover potential errors or rate limits.

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

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

Two sentences, front-loaded with key action and context. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (one parameter, read-only), description covers purpose, usage guidelines, behavioral traits, and hints at return fields. Lacks error handling or authentication details, but overall complete for the task.

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 one parameter 'url' with no description (0% coverage). Description adds 'resolve a social-media link' which gives context but does not specify format, constraints, or examples. Insufficient compensation for schema gap.

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

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

Description clearly states verb ('resolve'), resource ('social-media link to metadata and media URLs'), and scope ('without transcribing or running vision'). It differentiates from sibling socialdl_extract by noting it is 'cheaper' and for when 'caption/context alone is enough'.

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?

Explicitly says 'use when the caption/context alone is enough' and contrasts with socialdl_extract, implying when not to use it. This provides clear context but lacks explicit when-not-to-use or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds specific behavioral details about what data is returned (installed MCPs, connection status, catalog counts), providing context beyond the annotations without contradiction.

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

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

The description is a single sentence with all necessary information front-loaded. No superfluous words; every part adds 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, read-only tool with no output schema, the description fully specifies what the tool returns. The tool's complexity is low, and the description is sufficiently complete.

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

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

With zero parameters, the baseline is 4. The description does not need to add parameter semantics, and it appropriately omits any irrelevant parameter details.

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

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

The description uses a specific verb 'returns' and clearly identifies the resource ('current toolkit state') with detailed contents ('installed MCPs, their connection status, and how many catalog tools each exposes'). This effectively distinguishes it from sibling tools like 'authenticate' or 'connect'.

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

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

The description implies usage (for introspection) but does not explicitly state when to use it vs. alternatives, nor does it mention when not to use it. It is adequate but lacks explicit guidance.

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