Social → Context

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

Annotations already indicate safe, idempotent behavior. The description adds valuable context: token optional, returns a link if omitted, and distinguishes permanent vs session login. 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?

Two sentences packed with information. No wasted words. Clearly structured: first sentence states purpose, second explains the two usage paths.

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, but the description covers behavior for both arg cases. Could mention response format (link text), but context is sufficient for an authentication 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 has 0% description coverage, but the description fully explains the 'token' parameter: accepts a JWT for session login, optional if user wants the link. Adds complete 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 the tool's purpose: authentication for IDE agents. It explains the two workflows (permanent config vs session token) and distinguishes itself from sibling tools like 'connect' and '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 tells when to use each variant: 'add it to this server's config ... for a permanent, non-expiring connection' or 'paste it here for a session-only login'. No ambiguity about alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's role is to add context beyond those. It does so by detailing the two return states (authenticated vs. missing credentials), which aligns with and enriches the annotations. No 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?

Two sentences, front-loaded with the core function, and no wasted words. It is concise and well-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 no parameters and no output schema, the description covers the two key scenarios adequately. It does not mention partial connectivity states, but for a simple status check, it is sufficiently complete.

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

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

The input schema has no parameters and 100% coverage, so the description does not need to add parameter info. Baseline 4 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 what the tool does: returns connection status and URLs. It distinguishes between two scenarios (all connected vs. missing credentials), which differentiates it from siblings like 'authenticate' (which performs authentication) and 'toolkit_info' (general 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 explains when to use the tool (to check connection status) and implies not to use it for authentication (use 'authenticate' instead). It does not explicitly list alternatives, but the sibling context helps. For a zero-parameter tool, this is clear enough.

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

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

The description discloses key behavioral traits beyond annotations: invoke works even when the MCP is not installed, returns a connect link when credentials are needed, a checkout link when the wallet is empty, and writes require workspace owner/admin. These are critical operational details not captured by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint. 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 a dense single-paragraph block of ~300 words covering many concepts. It is informative but not tightly structured; it could benefit from bullet points or separate sections for readability. It includes a non-English word ('pontualmente') that may confuse. Every sentence adds value, but the organization is suboptimal.

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 complexity (14 actions, 23 params) and no output schema, the description covers the primary flow, edge cases (one-off invoke, credential links, permission requirements), and the separate prompt library. It does not specify return formats for every action, but provides enough context for an agent to use the tool correctly in most scenarios.

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 description explains the main action values (search, describe, invoke, install, list_tools, subscribe/cancel, report_bug, request_mcp) and the relationship between query, mcp_id, tool_id, and arguments. However, with 23 parameters and 0% schema coverage, many parameters like immediate, tier_slug, and most prompt_* fields are left undocumented. It partially compensates for the schema gap but not exhaustively.

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 what the tool does: it is 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' This establishes a specific verb (catalog/run) and resource (MCPs/tools). It also distinguishes itself from sibling tools by enumerating its multi-action role (search, describe, invoke, install, etc.), unlike connect or authenticate.

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 guidance, e.g., 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT.' It also enumerates when to use each action (list_tools, subscribe/cancel, report_bug, request_mcp), giving the agent clear decision rules and alternatives.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds context by mentioning the conversation array for reproduction, but does not explain side effects or outcome beyond the action itself.

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 with only two sentences, both front-loaded with essential information: first sentence states purpose, second gives specific usage instruction. No unnecessary words.

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

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

The description covers the core functionality for a simple feedback tool, but lacks information on expected outcomes (e.g., confirmation, storage), and does not mention that the tool is idempotent (as per annotation). It is adequate but not fully comprehensive.

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 must compensate. It explicitly explains the 'conversation' parameter ('Include the conversation array with recent messages for reproduction'). However, 'message' and 'context' are not described, though 'message' is implied by the tool's purpose.

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: 'Report a bug, missing feature, or send feedback.' It uses specific verbs and resources, and distinguishes itself from sibling tools which are unrelated.

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 specific instruction to 'Include the conversation array with recent messages for reproduction,' which hints at when to use (when reporting bugs requiring reproduction). However, no explicit comparisons to alternatives or when not to use are given.

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, idempotentHint, and destructiveHint. Description adds that it shows versions but no further behavioral details (e.g., output format, network request).

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, front-loads purpose, no extraneous 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?

Tool is simple; description covers purpose and resource. Could mention output format but not essential for a version display 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?

No parameters exist, and schema coverage is 100%. Baseline 4 for 0 parameters as per guidelines.

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 'Show' and specific resources 'MCP platform and adapter versions', distinct from 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?

No explicit when-to-use guidance, but the tool's purpose is clear and there are no sibling tools for version display, so usage is implicitly obvious.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context about supported platforms and that no transcription/vision occurs. However, it does not disclose potential rate limits, authentication needs, or whether the output includes metadata, which would add value 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 sentences with no wasted words. The purpose is front-loaded, and the second sentence provides clear usage guidance. 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?

No output schema exists, but the description mentions 'every video quality, audio track and image, with quality labels.' Still, the exact format of the response is unspecified, which may leave an agent uncertain about parsing. For a simple tool with one parameter, the description is decent 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?

Schema description coverage is 0%, but the description explains that the 'url' parameter accepts TikTok/Instagram/YouTube links or direct .mp4/image URLs, adding significant meaning beyond the bare schema type definition.

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 resolves TikTok/Instagram/YouTube links or direct media URLs to direct download URLs with quality labels. It specifies the verb (resolve) and the resource (download URLs from source CDN) and distinguishes from siblings like socialdl_extract 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?

The description explicitly says to use when the user wants to download/save media instead of transcribing it, and notes 'No transcription/vision.' This provides clear when-to-use and what-not-to-do, though no direct alternative sibling is named.

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, destructiveHint=false, establishing safety. The description adds behavioral detail about YouTube using existing captions. It does not disclose potential errors, rate limits, or the exact output format beyond the general list. With annotations covering safety, the description provides moderate added value.

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 with two sentences. The first sentence packs essential information effectively, and the second provides a usage instruction. While dense, it avoids redundancy and is well front-loaded. Minor improvement could be splitting the first sentence for readability.

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 complexity (4 parameters, no output schema), the description gives a high-level view of the output (metadata, transcript, vision description) but does not specify the structure or how parameters control output. It covers the main use case but leaves gaps for effective invocation, such as handling unsupported platforms or optional parameters.

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 has 4 parameters (url, language, transcribe, describe_images) with 0% schema description coverage. The description explains the output includes transcript and vision description, implicitly linking to transcribe and describe_images, but does not explain the 'language' parameter or clearly connect parameters to behavior. This falls short of compensating for the lack of schema descriptions.

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 downloads a social media link and returns text context including metadata, transcript, and vision description. It lists supported platforms (TikTok, Instagram, YouTube, direct .mp4), distinguishing it from sibling tools 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?

The description provides explicit usage guidance: 'Use this to give Claude the content of a video or post the user pasted.' It also notes that YouTube uses existing captions when available. However, it does not explicitly state when not to use this tool or directly compare to siblings like socialdl_metadata for simple metadata retrieval.

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. The description adds that the tool is 'lightweight' and 'cheaper', and explicitly states it does NOT transcribe or run vision. This adds value beyond annotations, though it could mention rate limits or other constraints.

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

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

The description is a single, well-structured sentence that front-loads the main purpose and uses a dash to add clarifying details. Every word is meaningful, with no redundancy or filler.

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

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

Given the simplicity of the tool (1 parameter, no output schema, rich annotations), the description covers all essential aspects: purpose, usage guidance, behavioral constraints, and return value structure. It is complete for an agent to understand 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?

There is only one parameter (url) with zero schema description coverage. The description does not add any constraints or format expectations for the URL, such as supported platforms or validation rules. The agent must infer from the context that it should be a social-media link URL.

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 is a 'lightweight lookup' for social-media links, returning metadata and media URLs without transcribing or vision. It explicitly distinguishes from the sibling tool socialdl_extract, making the purpose unambiguous.

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

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

The description explicitly tells when to use this tool ('when caption/context alone is enough') and contrasts it with socialdl_extract, which is the alternative for full transcription/vision. This provides clear usage 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, idempotentHint=true, and destructiveHint=false, fully covering safety. The description adds context about the return content but does not disclose any additional behavioral traits beyond what annotations provide. The bar is lower due to annotations, but still no extra transparency.

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

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

The description is a single sentence that is concise and front-loaded. It contains no filler and every part earns its place. Perfect conciseness for a simple status tool.

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

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

Given no parameters and no output schema, the description sufficiently covers the purpose and return content. However, it does not mention whether authentication is needed or if the result is cached. Still, for a simple informational tool, it is largely 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?

There are no parameters; schema coverage is 100%. The description adds meaning by explaining what the tool returns, which is valuable since the schema is empty. Baseline 4 is appropriate for zero-parameter tools when description adds context.

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

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

The description clearly states the tool returns the current toolkit state, including installed MCPs, connection status, and catalog tools count. It uses a specific verb 'Returns' and resource, and distinguishes from sibling tools like 'connect' or 'marketplace' which perform different actions.

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 checking toolkit state, but does not explicitly state when to use it vs alternatives. No when-to-use or when-not-to-use guidance is provided. Since the tool is simple and read-only, the implied usage is adequate but not explicit.

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