Ads MCP

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

Annotations already mark readOnlyHint=false and idempotentHint=false, so the writing nature is implied. The description adds the important consent and onboarding context, but it does not disclose what happens on repeated calls or what the tool returns, leaving some behavioral ambiguity.

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 short sentences with the key constraint front-loaded. Every phrase earns its place and there is 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?

For a lightweight one-parameter tool with no output schema, the description adequately covers purpose, scope, and consent requirements. Minor missing context includes duplicate-call behavior and expected return value, but these are low-risk for an onboarding check-in.

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%, and the single agentId parameter is fully documented by the schema. The tool description adds no parameter-level detail, which is acceptable since the schema already carries the 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?

States a specific action (records check-in), a specific resource (successful AdKit usage after setup), and a strict scope (onboarding only). This clearly distinguishes it from siblings like adkit_setup or adkit_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?

Provides clear usage context: onboarding, setup and connection verification, and only at the user's explicit request. It also excludes non-onboarding use via 'Onboarding only' and 'solely,' though it does not explicitly name alternative 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?

The annotations provide basic mutability hints, but the description adds valuable behavioral context: fire-and-forget semantics, that it never blocks the user's task, and a clear privacy boundary excluding secrets, tokens, bodies, uploaded files, and personal data. This goes beyond the structured 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 compact and front-loaded with purpose. The field list is short and earns its place by adding filling guidance rather than just repeating the schema, and the privacy rule is a single necessary sentence. No 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?

For a fire-and-forget feedback tool with no output schema, the description covers what triggers it, what fields to populate, the expected non-blocking behavior, and what to omit. It does not explicitly state what the tool returns, but the fire-and-forget framing makes that less critical.

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 baseline is 3. The description adds practical guidance by saying fields should be filled with whatever is known, giving a concrete context example with toolPath/platform/accountId, and reinforcing the sensitive-data exclusion. This elevates it above the schema-only case.

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 states a specific verb ('Report'), the target resource (AdKit), and enumerates accepted categories (bug, confusing behavior, missing capability, product feedback). It is clear and specific, though it does not explicitly distinguish itself from the sibling tool adkit_help.

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 context for when to use the tool: to report a bug or feedback, and it calls out the fire-and-forget, non-blocking nature. It does not explicitly name alternatives or state when not to use it, but the conditions are reasonably 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 establish read-only, idempotent, non-destructive behavior, and the description adds navigational behavior: progressive drill-down, q-based keyword search across the full catalog, and cross-path fallback semantics. It does not contradict the annotations, though it could describe the return/response format more explicitly.

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-organized sentences carry the full contract: the first establishes the catalog categories, the second gives concrete invocation patterns and search behavior. It is dense but front-loaded and free of 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?

For a help tool with no required parameters and rich annotations, the description covers root invocation, drill-down paths, keyword search, and precedence semantics, with examples. The lack of an output schema is not a gap because the return is clearly help content.

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 covers 100% of the parameters, so the baseline is 3; the description adds value with worked examples for path and q and clarifies that q searches the entire command catalog. This extends the schema documentation meaningfully without redundancy.

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?

Clearly identifies this as the AdKit help/discovery tool with a specific verb ('discover') and resource (the AdKit MCP contract). The top-level path categories distinguish it from sibling operation tools and make its scope concrete with examples.

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: start with adkit_help() for the root overview, drill down via path, or use q for keyword search. The directive to search before telling a user a capability is unavailable, plus the note that a capability may exist under another path, is strong 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, destructiveHint=false, idempotentHint=true, which signal safe read-only operations. The description adds that reports are 'native read-only' and directs users to adkit_help for deeper behavioral details, but does not explicitly mention connection complexities or multi-login scenarios, though the schema's connectionId parameter implies that. Overall, strong alignment with annotations plus value addition.

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 waste. It front-loads the primary purpose and immediately directs to adkit_help for further information. This is concise and structurally effective, though it could be slightly more self-contained by including a brief summary of the two actions.

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 tool is moderately complex with nested objects and two actions, but the schema is fully documented (100% coverage) and the description references adkit_help for advanced details. With no output schema, the description doesn't need to cover return values. The description is sufficient for basic invocation, but for advanced report building it relies on external help, which is a slight gap.

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 parameters are well-documented in the schema itself. The description does not add new semantic nuance beyond what the schema provides (e.g., that 'report' is the native GA4 runReport body). Therefore, a baseline of 3 is appropriate, as the schema carries the heavy lifting and the description adds minimal extra 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 reads GA4 properties and runs native read-only reports, with a specific reference to adkit_help for more details. It names the two actions (list_properties and run_report) which distinguishes it from other adkit tools that are not GA4-related.

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 instructs to call adkit_help for actions and report fields, providing a clear path for when to seek more information. It differentiates itself from siblings by being GA4-specificming, and the schema's action descriptions (e.g., list properties vs run report) offer additional usage context.

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 are sparse (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the description carries the burden. It discloses side effects like track/untrack changing the watchlist and boards update/creation altering metadata. It also mentions the safety rule about sharing. No contradiction with annotations. Lacks explicit detail on reversibility or exact consequences, but is nonetheless transparent enough for most agent use cases.

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 dense but well-structured. It opens with the core purpose, then adds critical scoping and safety constraints, and ends with a pointer to a sibling tool. Every sentence adds necessary information; there is no fluff 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 complexity (multiple entities, actions, and a free-form params object), the description covers almost everything an agent needs: scope semantics, projectId requirement, board sharing safety, and differentiation from adkit_manage. No output schema is present, but the description doesn't overpromise return details. The only minor omission is explicit pagination/return format, but that is not essential 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?

Schema coverage is 100% (all params have descriptions), so baseline is 3. The description adds extra value by clarifying the semantics of params.scope for library vs watchlist, and specifying which actions apply to which entities and when id/projectId are required. This goes beyond schema descriptions and helps the agent construct correct calls.

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 states a specific purpose: browse ads across platforms, track advertisers, and save ads to boards. It clearly distinguishes from sibling adkit_manage by noting the user's own campaigns live there. This differentiates it from other tools without ambiguity.

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

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

Provides explicit usage context: explains the scope parameter (library vs watchlist), instructs when to enable sharing (only when the user explicitly asks), and directs users to adkit_manage for their own campaigns. This gives clear when-to-use and when-not-to-use guidance, going beyond basic function description.

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?

Even with annotations present, the description adds valuable behavioral context: most mutations create drafts by default, publish:true requires explicit user approval, and coverage differs per platform. These details go well beyond the structured annotations and correctly align with readOnlyHint:false and destructiveHint:true.

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 long but well-organized and front-loaded with the primary purpose. Each paragraph covers a distinct concern (reporting, management, platform coverage, drafts, raw API, uploads), and while dense, the sentences are information-bearing rather than 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?

For a complex 10-parameter tool with no output schema, the description covers mutations, reporting, uploads, account resolution, and alternatives. It appropriately defers platform-specific entity/action details to adkit_help, which is a reasonable completeness strategy rather than a gap.

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, but the description adds meaningful usage rules: use AdKit field names, pass full request bodies as top-level data, use platformOverrides for raw fields, and distinguish id vs ids[]. This clarifies intent beyond the bare parameter 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 opens with 'Manage AND report on Meta, Google... Ads', clearly stating the verb, resource, and scope. It also distinguishes this tool from siblings by routing documentation to adkit_help, reporting gaps to adkit_feedback, and unsupported workflows to the raw platform API.

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 when-to-use guidance: reporting vs management, platform-specific entity docs under adkit_help, unsupported resources via platform-api-request, and gaps via adkit_feedback. It also explains file upload flow and draft publication, making it easy for an agent to decide between this tool and its 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=false and destructiveHint=false, so the mutation-without-destruction profile is conveyed structurally. The description adds value by disclosing that 'List also returns accessible workspaces,' a non-obvious behavioral trait, and the schema adds replace-semantics for tags ('Updating replaces the full list'). The description does not contradict the 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, each with a distinct job: sentence one states the core purpose, sentence two gives the critical workflow constraint, sentence three discloses a non-obvious return value. There is zero filler or repetition of schema content, and the purpose is 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 12-parameter, three-action tool with no output schema, the definition is largely complete because the 100%-covered schema thoroughly documents action-scoped parameter applicability. The description covers the essential ordering constraint (list to obtain projectId for update and other tools) and the workspaces return. The only real gap is that neither the description nor an output schema hints at what create/update return, leaving the agent to infer that create yields a projectId.

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 baseline of 3 applies and the description rightly leans on the schema for parameter meaning. The schema descriptions are genuinely rich — the action enum defaults to 'list', projectId is marked required for 'update', limit has defaults and max — so the tool's parameter semantics are fully conveyed without the description needing to repeat them.

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

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

The description opens with 'List, create, or update AdKit projects' — a specific multi-verb statement tied to a named resource that instantly tells an agent what the tool does. It also distinguishes the tool from siblings by identifying it as the project entry point in the AdKit family, complementing rather than duplicating the purpose of adkit_studio, adkit_manage, or adkit_library.

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 second sentence, 'Use a projectId returned by list for update and other project-scoped tools,' establishes a clear list-first workflow and routes the agent from this tool to dependent project-scoped operations. It provides clear context for the primary usage pattern, though it stops short of naming specific alternatives or stating explicit when-not-to-use conditions.

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 readOnly, idempotent, and non-destructive hints, so the description does not need to restate those. It adds useful behavioral context beyond the annotations by noting that it is browser-based and that the result is dashboard URLs the user can open.

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 short sentences carry all the essential information: what the tool does, the key dependency, and what it returns. No filler or redundant restatement of the title or schema is present.

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 tool with only three parameters, full schema coverage, and annotations covering safety traits, the description is largely complete. It explains the return value and the main prerequisite, though it slightly overstates projectId as unconditionally required when the schema allows auto-resolution for single-project users.

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 all three parameters and their enum values. The description only repeats the projectId dependency from adkit_projects without adding new parameter-level meaning, keeping this at 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?

The description clearly states the tool launches browser-based AdKit setup flows, which is a specific verb and resource. It does not explicitly differentiate itself from sibling tools like adkit_manage, but the setup flow focus and return of dashboard URLs are distinctive enough for an agent to understand its purpose.

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 it requires projectId from adkit_projects, giving an agent a clear prerequisite and pointing to the correct sibling tool for obtaining that ID. It does not state explicit when-not-to-use scenarios, but for a focused setup tool this is adequate 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/idempotentHint/destructiveHint, and the description adds what data is returned. However, 'Requires projectId' is slightly overstated because the schema notes the parameter auto-resolves for single-project users, and no edge-case behavior is disclosed. 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?

One sentence that front-loads the return contents and immediately states the dependency. 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?

The description explains what the tool returns and the input dependency. It lacks an explicit call scenario or output-shape details, but given a single parameter and read-only safe operation, it is nearly 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 100% schema coverage, the description adds no new parameter meaning; it simply repeats that projectId is required and sourced from adkit_projects, which the schema already documents.

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 ('Return') and a precise resource ('project context, connected platforms, assigned ad accounts, and Studio setup'), which clearly identifies the tool as a status/read-only lookup and distinguishes it from sibling tools like adkit_projects or adkit_setup.

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?

It explicitly states the prerequisite: projectId must come from adkit_projects. This tells the agent which prior tool to call. It does not name alternatives or exclusion cases, so it misses the highest bar, but the usage context 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?

Annotations already signal readOnly=false and destructiveHint=true; the description adds meaningful behavior beyond that: Studio entities are drafts, no live campaign data is exposed, and the temporary-upload workflow requires a PUT before passing the reference. It does not detail side effects of delete/update, but the key conceptual boundary is well disclosed.

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 dense but efficiently organized: capability overview, critical action mapping, the upload workflow, and boundary with adkit_manage. Every sentence contributes guidance an agent needs, and no space is wasted restating the tool name or schema.

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 multi-entity, multi-action tool with nested params and no output schema, the description covers the major decision points: which entity/action combos to use, id behavior, the upload sequence, and where live data lives. It does not describe return payloads, but that is a minor gap given the breadth of operations and the strong schema coverage.

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, but the description enhances it materially with action-specific id semantics ('omit to auto-create' vs 'provide id to add variants'), the temporary_upload reference shape, and example enum values for model/quality. It leaves a few actions to the schema, but adds real operational meaning beyond the property 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 opens with a specific role: 'AI ad generation workspace' and enumerates concrete operations (create briefs, generate images, list media, inspect media items, share briefs). It also distinguishes itself from adkit_manage by explicitly stating Studio ads are creative drafts, so an agent can separate this tool from its siblings.

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

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

It gives explicit routing instructions: use entity 'ads' with action 'generate', omit or provide id depending on variant behavior, and use the media request_upload_url flow for user photos. It also states what the tool does NOT contain (live campaign data/spend/performance) and directs that data to adkit_manage, which is clear when-not 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 signal a mutating external operation (readOnlyHint=false, openWorldHint=true). The description adds useful behavioral context beyond annotations: the beta status, X's JPEG/PNG-only limitation, unsupported input methods, and a failure reporting path. It does not detail duplicate creation or auth requirements, but it does not contradict the 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 six short, dense sentences with the core operation front-loaded. Every sentence earns its place: beta warning, destination platforms, accepted source types, X restriction, fallback behavior, unsupported inputs, and error routing. There is no filler or redundant repetition of schema content.

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 complex 9-parameter upload tool with no output schema, the description covers the main invocation paths, source selection, platform destinations, and important limitations; the rich schema descriptions handle parameter details. It is slightly incomplete regarding what the tool returns after request_upload_url or a successful upload, but the core calling contract is clear.

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 parameters are already well documented in the schema. The description adds semantic constraints not present in the schema: base64/local paths are invalid, X supports only JPEG/PNG, and a requested upload URL substitutes when no attachment or public URL exists. This lifts it above the 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?

The description opens with a specific verb and resource: 'Upload one file to Meta, Google, TikTok, LinkedIn, X, or Studio.' It also enumerates the supported source types and includes a platform-specific format caveat, making the tool's purpose unmistakable and distinguishable from sibling tools like adkit_library or adkit_studio.

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?

It provides explicit when-to-use guidance: attach a file, use a public HTTPS URL, use a completed temporary upload, or request an upload URL when no attachment/public URL exists. It also states clear exclusions ('Base64 payloads and local file paths are not accepted') and routes failures to adkit_feedback.

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