Adako: Google Ads, Meta Ads & Linkedin Ads MCP

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

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing the confirmation protocol (quote the proposal summary), the cost model ('free, not counted against tasks'), that the object is read back after execution, and the exact error behavior on expired/decided proposals. These are operational traits an agent cannot infer from 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?

Front-loads the destructive warning, then states the core action, prerequisites, use case, and error handling. Every sentence carries distinct information with 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?

Despite no output schema, the description notes it 'reads the object back', covers the confirmation prerequisite, cost, and failure modes. Nothing an agent needs to invoke this correctly is missing.

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 proposal_id, idempotency_key, and raw_data. The description's 'exactly once' phrasing hints at the idempotency guarantee, but that is already covered by the idempotency_key schema description, so it adds little param-level meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('Executes a pending proposal exactly once and reads the object back'), and clearly differentiates from siblings like list_pending_proposals and reject_proposal. An agent can tell what this does without opening the schema.

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

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

Explicitly states when to call ('Only call after the user has explicitly said yes', 'the user's write policy is "inbox"') and provides a failure rule ('If the proposal expired or was already decided... do not re-create it silently; tell the user'). This is genuine when/when-not guidance with a clear alternative action.

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, and the description reinforces this ('nothing called here changes anything'), which is consistent rather than contradictory. It adds value beyond the annotations by disclosing cost behavior (list_tools/get_tool_schema are free, execute bills the tool) and the 20-account fan-out cap. It does not describe return shape or error behavior, but with no output schema that is a minor gap for a router.

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?

Purpose and the write-sibling boundary are front-loaded, followed by the invocation pattern and a compact category map of routable tool names. The categorized tool list is dense but earns its place by telling the agent what it can reach; a little tightening of the repeated 'free like every read' phrasing would help.

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 dispatcher with a nested arguments object and no output schema, the description supplies everything needed to invoke correctly: the action enum semantics, the accounts behavior/cap, the exactness requirement on tool_name, cost model, and the set of reachable tools plus the one read that lives outside the router.

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 meaningfully enriches the schema: it explains that accounts produces 'one read across up to 20 accounts' that is free, and stresses that tool_name must be exact and never guessed. This adds operational meaning beyond the field 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?

States a specific verb and resource ('Reads and tool lookup for ChatGPT Ads') and immediately draws the boundary against its write sibling: 'The 13 ChatGPT Ads tools that change something run through chatgpt_ads_write.' An agent can tell this router apart from chatgpt_ads_write and chatgpt_get_performance without opening any schema.

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

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

Gives explicit routing rules: use action='list_tools' / 'get_tool_schema' (free) before executing, 'never guess a tool_name', and names the sibling called outside this router (chatgpt_get_performance). The free-vs-billed distinction for reads versus execute is stated outright.

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 destructiveHint=true and non-idempotent, but the description adds behavior the annotations cannot express: every call creates a user-approved proposal before anything changes, creates land PAUSED, and one account per call with no fan-out. These are exactly the mutation-safety facts an agent needs.

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

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

Front-loaded with the scope and the routing exclusion, then the invocation shape, then the category list. The 13-tool enumeration is long but serves routing, so it earns its place; minor density cost only.

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

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

There is no output schema, and the description fills that gap by explaining the proposal/approval response cycle. For a 3-param router with full schema coverage this is effectively complete, lacking only details like proposal expiry or error behavior.

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 it already documents action/tool_name/arguments. The description nonetheless adds the semantic constraint that 'execute is the only action', reinforcing the single-valid-value enum the schema implies but does not enumerate.

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

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

States a specific verb class ('create, update, pause or remove') and resource ('ChatGPT Ads'), scopes it precisely ('the 13 ... write tools'), and explicitly declares what it is NOT ('Reading, listing or checking anything is not here'). An agent can distinguish it from the chatgpt_ads read router without opening the schema.

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

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

Gives explicit when-to-use and when-not-to-use: lookups belong to chatgpt_ads and 'calling this router to look something up is always wrong'. It also names the cheap alternative (chatgpt_ads(action="get_tool_schema")) for schema discovery.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds cost semantics (free, not counted against tasks), window edge behavior ("last N days" end yesterday so no partial day is mixed), the meaning of a dash in the change column, ROAS empty-vs-zero behavior, and default-on comparison. This is well beyond annotation coverage.

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

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

Front-loaded with the highest-value facts (read-only, free) before what it returns, then usage, then caveats. Dense but each sentence carries distinct information; slightly long for an 11-parameter read tool but nothing is clearly wasteful.

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, so the description carries return-value explanation and does so thoroughly: currency-as-decimal spend, per-metric percentage change vs previous period, dash semantics, and ROAS caveat. Combined with full routing guidance and safety annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the three ID scoping parameters and what happens without them (whole account), reiterates the date_range vs start/end exclusivity, and confirms compare_previous defaults on. This enriches schema without fully duplicating it.

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

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

States a specific verb (read/report) and resource (ChatGPT Ads performance) plus the exact metrics returned (impressions, clicks, spend, conversions, CTR/CPC/CPM/CPA/ROAS) and the breakdown levels. It clearly differentiates itself from sibling performance tools by naming the platform and from monitoring/generate_report_now explicitly.

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 ("user asks how anything is doing"), when-not-to-use (not for briefs/reports → generate_report_now; not for discovery → chatgpt_list_campaigns), scoping guidance, and even a diagnostic escalation path for all-zero results. Alternatives and their selecting conditions are 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 cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: cost is free and not counted against tasks, it repairs share links (Drive/Dropbox/etc.), fetches only the head of the file, Adako hosts nothing and the platform downloads the URL later, and local paths/login-gated/expiring links cannot work. This is genuinely useful behavioral disclosure.

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

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

Front-loads the read-only/cost facts and organizes into clear labeled sections. Slightly verbose with some repetition (free/read-only/creates-nothing restated across sentences), but nearly 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 zero-required-param, four-parameter tool with no output schema, the description covers invocation modes, defaults, hosting semantics, and retry guidance. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the no-argument behavior (returns the three cheapest ways to obtain a link) and reinforces the repair-not-reject semantics, though the platform default behavior is largely duplicated from the schema. Marginal but real added value.

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

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

States a specific verb (checks) and resource (a creative file — image or video) with explicit scope ('before any ad is built from it'). An agent can immediately distinguish it from the create tools and platform siblings that take image_url/video_url.

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

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

Explicit when-to-use: 'the user offers an image or a video in any form... and always before a create tool that takes image_url or video_url.' It also names the no-argument invocation case ('when the user has a file but no link') and routes refusal handling ('never retry a create with the same file').

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, so the safety profile is covered. The description adds genuinely useful context beyond that: the cost asymmetry between free lookup actions and billed execute, and the account-fan-out ('free like every read, max 20'). It says nothing, though, about what an execute call actually returns.

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 lead sentence front-loads the read-only nature and the dispatch pattern, and the category list is compact and scannable. No wasted prose, though the tool roster is long and could be partially replaced by the free list_tools action it advertises.

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 dispatcher with no output schema, the description supplies what an agent needs to route correctly: the action modes, free-vs-billed behavior, and the tool inventory. It is only slightly short on describing the shape of execute results or error behavior.

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 every parameter (action, accounts, arguments, tool_name) including the enum values. The description reinforces 'never guess a tool_name' and the free/paid split but adds no new parameter syntax or format detail, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states this is a read/tool-lookup dispatcher ('Reads and tool lookup for Diagnostics') and enumerates the concrete sub-tools it fronts (explain_error, validate_campaign_draft, etc.), so the agent understands it is a gateway, not a single operation. It does not, however, distinguish itself from dispatcher-like siblings such as search_tools or start_here.

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 clear routing guidance for the action enum – list_tools and get_tool_schema are 'free' while execute bills – and adds the practical rule 'never guess a tool_name.' It stops short of stating when to prefer this tool over adjacent discovery tools like search_tools.

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

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

Annotations already declare readOnly, idempotent and non-destructive, yet the description still adds value beyond them: it states the call runs immediately, costs nothing against task quota, and touches Adako's database only with no platform calls. Those latency/cost/blast-radius disclosures are exactly what an agent needs to decide whether to call it mid-failure.

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

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

Front-loaded with the read-only/cost banner and the use-when condition early, which is the right ordering. The emoji and cost line are slightly decorative but genuinely informative for an agent budgeting calls, so little is wasted.

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

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

With no output schema, the description carries the return-value burden and does so: token health states and actionable fix links are described. Combined with the trigger conditions and cost model, an agent has everything needed to call this correctly in a failure path.

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?

Only one optional parameter (raw_data) and the schema already documents it at 100% coverage, so the schema does the heavy lifting. The description never mentions it, adding no syntax or formatting guidance. Baseline 3 is appropriate.

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

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

States a specific resource and scope: every connected platform login, its token health (active / needs re-authorisation / revoked), and the active + primary ad accounts under it. It's clearly distinguishable from the many *_ads_write and performance siblings. It does not explicitly distinguish itself from list_connected_accounts, the nearest sibling, which weakens it slightly.

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

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

Gives explicit trigger conditions: when a platform tool failed with not_connected or needs_reauth, or before the first platform call in a conversation. That is genuinely actionable. It names no alternatives or when-not conditions (e.g. vs list_connected_accounts), so it stops short of a 5.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so they set the floor; the description adds genuinely new traits: zero cost, not counted against tasks, never touches an ad platform, and the failure behavior for unknown names (near matches returned). It stops short of stating rate limits or output size limits for large batches, so 4 rather than 5.

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

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

Front-loads the most decision-relevant facts (read-only, free, what it returns), then routes with use-when / when-not-to-use, then return shape. Dense with useful content, though the cost statement is repeated in two places and the emoji line is decorative rather than informative.

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, and the description compensates by describing the return shape (one block per tool with risk, cost, the 'How to call' line and the schema) plus a compact mode. Combined with full parameter coverage and annotation-backed safety, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and each parameter is documented in the schema itself, so the baseline is 3. The description restates verbose=false behavior and hints at batch size ('one or more', schema caps at 10) but adds nothing the schema does not already say, and never mentions raw_data.

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

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

States a specific verb and resource — 'Returns the live JSON schema of one or more tools' — and enumerates what comes back (required fields, enums, defaults, examples, call line). It is clearly distinguishable from sibling search_tools, which discovers tools rather than describing them, and the title reinforces the same 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?

Contains explicit 'Use when' conditions (a router or search_tools pointed at a tool; a call failed validation) and an explicit 'When not to use' (the schema is already attached to a tool in the tool list). The alternative, search_tools, is named as the fallback for unknown 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 already cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: it is free and not counted against tasks, it reads only Adako's database, it defines 'task' as one billable tool call, and it explains that a switched-off ad account keeps its plan slot.

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

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

Front-loads the read-only/cost guarantee before the return payload and the trigger conditions, and the trailing definitions of 'task' and account retention each earn their place.

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

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

No output schema exists, but the description enumerates the returned fields (plan, tasks used vs limit, reset, ad accounts vs limit, plans link), so an agent knows what it will get; safety and cost are also fully covered.

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?

Only one optional parameter (raw_data) and schema description coverage is 100%, so the schema already documents it fully; the description adds nothing about the parameter. Baseline 3 is appropriate here.

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?

Names a specific verb+resource (returns the user's plan, task usage vs limit, reset time, ad-account usage, plans link) and enumerates the exact payload, so it's clearly distinct from siblings like list_connected_accounts or diagnostics.

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

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

Gives explicit triggers: 'use when a tool returned quota_exceeded or account_limit, or the user asks how many tasks or accounts they have left.' That is a concrete when-to-use rule an agent can act on without inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description reinforces and extends this with billing behavior ('execute bills the tool'), the free-read model, and the 20-account fan-out cap. It does not explain the non-obvious idempotentHint=false, which is the one behavioral trait left unexplained.

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?

Purpose and scope are front-loaded in the first two sentences, followed by invocation syntax, account semantics, and the sibling exclusion. The 38-tool category listing is long but earns its place as a routing index that saves a list_tools round trip; a slightly tighter format would push this higher.

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 router with a nested arguments object and no output schema, the definition is nearly complete: it tells the agent to resolve tool names via list_tools/get_tool_schema and describes the account fan-out. It stops short of describing what a read returns or how results are shaped across multiple accounts.

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 baseline is 3, but the description adds real meaning beyond the schema: 'never guess a tool_name' operationalizes tool_name, accounts="all_active" semantics and the 20-account read fan-out are contextualized, and it clarifies that arguments is the target tool's own 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?

States a specific verb and resource ('Reads and tool lookup for Google Ads') and immediately delimits scope: 'nothing called here changes anything.' It explicitly contrasts itself with google_ads_write, so the agent can separate the read router from the write router without opening either schema.

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

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

Explicit invocation pattern is given (action="execute" with tool_name/arguments, list_tools and get_tool_schema free), plus the constraint 'never guess a tool_name.' It names the write alternative (google_ads_write) and even clarifies that google_get_campaign_performance is called by name outside this router.

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?

Beyond the annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true), the description discloses that every call creates a user-approved proposal before anything changes, that creations default to PAUSED, and that calls are constrained to one account with no fan-out. These are consequential behaviors the annotations alone do not convey.

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

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

Front-loaded with the routing rule and invocation signature before the catalog, and the length is justified by the need to enumerate 38 dispatch targets. Minor redundancy between 'reading, listing or checking anything is not here' and 'calling this router to look something up is always wrong', but the emphasis is arguably warranted for a misrouting-prone router.

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 mutation router with no output schema, the description covers what the agent needs: how to invoke it, which sub-tools exist, the approval/paused-creation workflow, and the one-account constraint. Nothing required for correct calling is missing.

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

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

Schema coverage is 100% and the schema already explains action/arguments/tool_name, so the baseline is 3. The description adds real value for tool_name by enumerating the 38 valid values grouped by category, which the schema only bounds by minLength/maxLength 64.

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

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

States a specific verb and resource ('the 38 Google Ads tools that create, update, pause or remove something') and explicitly names the read sibling google_ads as the thing it is not. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit when-not guidance ('reading, listing or checking anything is not here — that is google_ads, and calling this router to look something up is always wrong') and points to the free schema lookup path via google_ads(action="get_tool_schema"). The alternative and its selection condition are both stated.

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?

Beyond the readOnly/idempotent annotations, it discloses cost ('free, not counted against tasks'), timezone semantics, currency semantics, and the important null-vs-zero behavior for CPA/ROAS with an instruction on how to report blanks. It also advises asking the user rather than guessing ids or dates. 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?

Front-loaded with a safety/cost banner, then use/don't-use routing, then parameter notes. Slightly long, but nearly every sentence carries operational value; only the emoji-banner line is arguably decorative overhead.

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

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

With no output schema, the description compensates by naming the returned metrics, the period-over-period comparison, and null-handling conventions. Combined with complete schema documentation, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema does not: the date_range vs start_date+end_date mutual exclusivity is emphasized as a hard rule, and periods are defined as calendar days in the account's timezone with money as decimal in account currency. It does not explain limit, raw_data, or campaign_ids beyond what the schema says.

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

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

States a specific verb and resource (reports campaign performance metrics) and enumerates the exact measures returned: spend, impressions, clicks, CTR, conversions, conversion value, CPA, ROAS, plus period-over-period change. It also explicitly distinguishes itself from generate_report_now, google_list_campaigns, and google_analyze_search_terms.

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 when' triggers (performance questions, improvement checks, cost per conversion), explicit 'Do not use when' cases with named alternative tools, and a routing note to generate_report_now for report deliverables. No inference required.

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, but the description adds genuinely new context: nothing changes state, reads are free, and only execute bills the tool. It does not describe return payloads or multi-account result ordering, so it stops short of a 5.

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?

Despite its length it is front-loaded (read-only framing first), organized into named sections and a category list, and every sentence carries routing or naming information an agent needs. 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?

Given the router complexity, 29 siblings and nested arguments, the description supplies the missing pieces: the October 2025 Campaign Manager renaming (campaign group vs campaign vs ad set), how to disambiguate user vocabulary, and which tools sit outside this router.

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

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

Schema coverage is 100% and the schema already covers action/accounts/tool_name/arguments. The description still adds real meaning: the free-vs-billed distinction, the all_active sentinel and the 20-account ceiling, and how arguments map to the inner tool's own 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?

States precisely that this is a read-only router/tool-lookup for LinkedIn Ads and that all mutating operations live in linkedin_ads_write. It even enumerates all 17 read tools by category, so an agent can identify the exact resource set without guessing.

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?

Explicit routing rules: use action="list_tools" or "get_tool_schema" (free) and never guess a tool_name; the one tool not in the router (linkedin_get_campaign_performance) is called by name. It also explains the accounts scoping, so both when-to-use and when-not-to-use are covered.

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

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

Annotations already mark it destructive, non-idempotent and open-world, but the description adds genuinely non-obvious behavior: every call creates a proposal the user approves before anything changes, and creates land PAUSED. The approval workflow and paused-by-default semantics are exactly the context an agent cannot get from the annotation flags.

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?

It is dense but well front-loaded: routing decision first, then the naming trap, then invocation, then the tool list by category. The October 2025 naming paragraph is long but earns its place because it prevents a real mis-parameterization (campaign vs ad set).

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 router over 17 sub-tools with no output schema, the description supplies everything needed: invocation shape, the read/write boundary, the naming disambiguation, approval and pause behavior, and the full category inventory. No material gap remains for correct 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 coverage is 100%, so the three parameters are already documented. The description still adds value by pinning action to the single valid value 'execute' and clarifying that tool_name is the exact name of the mutating tool, plus that list_tools/get_tool_schema live on the read router. Slightly beyond the schema-only 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 states a specific role (the 17 LinkedIn Ads write tools that create, update, pause or remove) and immediately names the sibling it is not: linkedin_ads, the read router. An agent can distinguish this router from linkedin_ads without opening either schema.

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

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

It gives explicit when-not guidance ('Reading, listing or checking anything is not here... calling this router to look something up is always wrong'), points to linkedin_ads and linkedin_get_campaign_structure for lookups, and states the operative constraints ('One account per call, no fan-out'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: it is free (not counted against tasks), defines the comparison window behavior, notes LinkedIn ad accounts carry no reporting timezone (all UTC days), explains typical B2B volume noise, and warns not to misread CPC rises or zero-lead campaigns. This is rich, non-redundant 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?

Well-structured with a clear READ-ONLY banner, metric list, use/don't-use routing, and behavioral notes. Each sentence earns its place by providing unique guidance. Slightly verbose (multiple do/don't blocks and repetition of baseline concept), but front-loaded and scannable.

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 9 optional parameters, no output schema, and complex reporting semantics, the description covers routing, defaults, timezone handling, and diagnostic follow-ups. It stops short of explaining the exact return structure (though no output schema exists, so some return-format disclosure would help). Nonetheless, it is complete enough 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 description coverage is 100%, so all nine parameters are fully documented in the schema itself (including defaults, enum values, date pairing rules, and the ad_account_id string format). The description mostly reinforces parameter semantics with usage-level guidance (default to last_30_days if unspecified, use last_7_days minimum, check conversions on zero leads) rather than adding syntax beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

States a specific verb+resource (reports LinkedIn campaign performance) and enumerates the metrics returned (spend, impressions, clicks, CTR, CPC, CPM, leads, cost per lead, conversions). It distinguishes itself from siblings by naming generate_report_now and the list tools as alternatives. An agent can identify the tool's role without opening the schema.

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

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

Explicit when-to-use ('user asks how LinkedIn is doing', 'before recommending any budget or bid change'), explicit when-not ('not for a brief or report to keep/forward — that is generate_report_now'), and directs alternative workflow ('start here, not with a list tool'). Also gives a default window recommendation and a diagnostic follow-up (linkedin_list_conversions). This is exemplary routing 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/idempotent/non-destructive, and the description restates the read-only banner redundantly. It nonetheless adds real context beyond annotations: free cost not counted against tasks, the per-period account quota, that only active accounts are usable, and per-platform primary-account semantics.

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

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

Front-loaded with the read-only/cost banner, then behavior, then usage triggers. Dense but each sentence carries information; the read-only restatement slightly overlaps the annotations.

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, so the description compensates by listing the returned fields (platform id, name, currency, timezone, active/primary) plus plan and ambiguity semantics. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are self-documented. The description notes the platform filter is optional and explains the primary-account concept, but adds no syntax or enum detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Lists every ad account Adako knows for this user') and enumerates the returned fields. It is clearly distinguished from siblings like switch_primary_account and the platform read 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?

Gives an explicit 'Use when:' clause with concrete triggers (user names an account, or a tool returned account_ambiguous/not_connected). This routes the agent cleanly against 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 cover read-only/idempotent/non-destructive, so the safety profile is redundant, but the description adds genuinely new traits: cost is free and not counted against tasks, and proposals carry a 48 h expiry. It does not describe return format or ordering, but the added cost/expiry context is meaningful.

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

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

Front-loaded with the read-only/cost banner and the core action, then use cases. Compact and structured, with only mild repetition of the annotations in the opening clause.

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

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

For a two-param, zero-required, read-only list tool with a fully documented schema and no output schema, the description supplies everything needed: what comes back (preview, expiry), when to call it, both modes, and cost.

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 both properties already document themselves; the description largely restates the proposal_ids semantics rather than adding syntax or limits beyond 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?

States a specific verb and resource ('Lists writes that were proposed but not yet approved') and names the concrete payload returned (preview and expiry). It also distinguishes the dual mode (pending-only vs. proposal_ids for any status), so an agent can tell it apart from approve_proposal/reject_proposal and the write 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?

Gives explicit triggers: 'the user asks "what is waiting for my approval"' or 'after a tool returned proposal_pending', and a separate trigger for the proposal_ids variant ('use it when the user asks whether a change went through'). Both when-to-use paths are spelled out.

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?

Beyond the annotations' readOnlyHint/destructiveHint, the description discloses cost semantics ("execute bills the tool", lookups and reads are free), a 20-account fan-out cap for accounts="all_active", and that list_tools returns the write half too. Billing behavior is material for an agent deciding whether to probe, and it is not present in the annotations or 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?

Front-loaded with the routing contract, then bolded category lists that genuinely aid discovery across 29 routed tools. Slightly repetitive (the free-read point is made twice) and the enumerated tool inventory is long, but the size is justified for a router of this breadth.

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?

A router with no output schema, 100% schema coverage and read-only annotations needs: routing contract, cost model, discovery path, and sibling ownership. All four are present, so an agent can call it correctly without further 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 coverage is 100%, so the structured baseline is 3, but the description adds real meaning over the schema: the free-vs-billed split per action value, the exact-match requirement on tool_name ("never guess"), and the all_active read fan-out. It stops short of explaining the nested arguments object beyond pointing back at the target tool's 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?

States a specific verb+resource pair ("Reads and tool lookup for Meta Ads") and immediately scopes it by declaring nothing here mutates state, routing all 16 write tools through meta_ads_write. An agent can distinguish this read router from meta_ads_write and from the per-channel routers without opening any schema.

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

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

Explicit invocation contract: action="execute"/"list_tools"/"get_tool_schema", "never guess a tool_name", and the two lookup actions are declared free. It also names the sibling that owns the write half (meta_ads_write) and the one tool deliberately excluded from the router (meta_get_campaign_performance), giving both when-to-use and when-not-to-use.

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

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

Given annotations already declare destructiveHint=true and openWorldHint=true, the description still adds substantial context the annotations cannot: every call creates a user-approved proposal before anything changes, creates land PAUSED, only 'execute' is a valid action, and there is one account per call with no fan-out. These are exactly the operational constraints an agent needs to avoid misuse.

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

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

Front-loaded with the critical read/write distinction and the invocation form, then the constraints, then the categorized tool list. The 16-name enumeration is long but earns its place for routing; only marginal tightening is possible.

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, and the description compensates by covering the approval workflow, the paused-create behavior, the single-account limit, and how to resolve sub-tool argument schemas. For a router with nested arguments this is nearly complete; it could still note where proposal status is checked (list_pending_proposals/approve_proposal).

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 all three parameters are already documented and the baseline is 3. The description adds meaning beyond the schema by framing the call shape (action="execute", tool_name, arguments={...}) and by pointing to meta_ads(action="get_tool_schema") as the free way to discover the invoked sub-tool's argument schema, which is genuinely useful for a router.

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

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

States a specific verb+resource: it is the write router for Meta Ads, carrying exactly the 16 tools that create/update/pause/remove. It explicitly names what it is not ('Reading, listing or checking anything is not here — that is meta_ads'), so an agent can distinguish it from the read router without opening either schema.

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

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

Explicit when-to-use (any change to Meta Ads), when-not-to-use ('calling this router to look something up is always wrong'), and the alternative (meta_ads, plus meta_ads(action="get_tool_schema") for free schema lookup). Both the positive and negative paths are stated, not inferred.

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 safety, but the description adds real behavioral context beyond them: the call is free and not counted against tasks, ROAS returns 'not applicable' rather than zero on non-revenue objectives, and vague date wording should trigger a clarifying question. This is exactly the kind of quirk disclosure that prevents agent misjudgment.

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

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

Front-loaded with the read-only/free banner, then use/no-use guidance, then the return quirk and the ambiguity rule — every sentence carries routing or behavioral weight. The multi-clause KPI enumeration is long but justified by the objective-specific output contract; slightly padding-prone but not wasteful.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does: window-over-window comparison plus per-objective KPI selection, and the 'not applicable' sentinel. Combined with the named alternatives and the date-input rule, an agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100%, so each of the seven parameters is already documented including the date_range exclusivity rule. The description mentions windows and the objective/KPI mapping but adds no syntax or format detail beyond the schema, which matches the baseline 3 for a fully-covered 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 gives a specific verb and resource — campaign-level results for a window compared against the prior equal-length window — and enumerates the objective-specific KPIs returned. It also explicitly distinguishes itself from three named siblings (generate_report_now, meta_list_campaigns, meta_analyze_wasted_spend), so an agent can route correctly without opening any schema.

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

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

It states when to use it ('how Meta is doing', budget reallocation, week-over-week change) and when not to, naming the alternative tool for each exclusion. It even covers the ambiguous-input case, telling the agent to ask for the window rather than guessing.

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, so the safety profile is partly structured. The description adds value the annotations do not: the billing model ('execute bills the tool'), the cost-free status of list_tools/get_tool_schema, and the account-wide read limit. It does not, however, explain why idempotentHint=false on an ostensibly read-only dispatcher, which is a residual gap.

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

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

Front-loaded with what the tool does and the no-mutation guarantee, then the calling convention, then the catalog. The catalog costs length, but for a dispatcher that is functional payload rather than filler. Minor redundancy with what list_tools would return at runtime.

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 meta-tool facing 30+ siblings, the description supplies the essential context: the read/write split, the sibling to use for writes, the discovery workflow, and a categorized inventory. With no output schema and 100% parameter coverage, the remaining burden is low; only the odd idempotency signal is unexplained.

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, and the description does add meaning beyond the schema: it clarifies the intent of the action enum (free lookups vs billed execute) and stresses that tool_name must be exact rather than guessed. The accounts and arguments parameters remain largely schema-documented, so this is a modest but real uplift.

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 first sentence names the verb (reads / tool lookup), the resource (Monitoring and reporting), and the scope boundary ('nothing called here changes anything'), immediately distinguishing it from the sibling monitoring_write. The catalog then enumerates each sub-tool with a one-line purpose, so an agent knows both the dispatcher's role and its contents.

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 an explicit workflow recipe (list_tools -> get_tool_schema -> execute), states which actions are free versus billed, warns 'never guess a tool_name,' and routes all mutating operations to monitoring_write. When-to-use and when-not-to-use are both covered with no inference required.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds non-annotation context: every call mutates state for the current user and calls must be issued one at a time. It does not state which of the listed operations are irreversible or what authorization is required, leaving some behavioral detail implicit.

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

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

Front-loaded with the scope and exclusion rule, then grouped sub-tools by category with a one-line effect for each — no filler. Slightly long, but a router that must enumerate 7 dispatched tools earns that length; the 'One per call' fragment is a touch terse.

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 3-parameter dispatch router with a nested arguments object and no output schema, the description covers routing rules, the exclusion against the read router, and the full catalog of target tools, and it points to get_tool_schema for per-tool detail. Error/response behavior is unspecified, but no output schema exists to conflict with that omission.

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 baseline is 3, but for a router the description adds real value: it gives the concrete invocation form monitoring_write(action="execute", tool_name="…", arguments={...}) and clarifies that tool_name is the exact name of the changing tool. This is slightly more than the schema fields state individually.

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 exactly what the tool is: the write router for the 7 Monitoring and reporting tools that create, update, pause or remove something. It enumerates all 7 sub-tools by name and effect, so an agent understands both the router role and the concrete capabilities without opening any schema. It also explicitly differentiates itself from the sibling read router 'monitoring'.

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 draws a hard line: 'Reading, listing or checking anything is not here — that is monitoring, and calling this router to look something up is always wrong.' It names the alternative router and points to monitoring(action="get_tool_schema") for schema lookups. This is explicit when/when-not guidance with the correct sibling 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 flag destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds genuinely useful context beyond them: the write changes only Adako-side settings ('nothing changes on an ad platform') and is free/not task-counted, which materially changes how an agent should reason about it. It stops short of explaining reversibility or what happens to the stored reason.

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

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

Front-loads the WRITE banner and lead sentence, and each section earns its place. Minor redundancy: cost is stated twice ('Cost: free' in the header and a trailing 'Free.').

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 mutation tool with no output schema, the description covers the effect, the trigger, the cost model, and the side-effect scope, with annotations carrying the safety profile. The only real hole is that it never points at where a valid proposal_id comes from.

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 50%; raw_data and idempotency_key are self-documented. The description adds real meaning for reason ('store the user's reason... it improves future proposals'), but proposal_id — the required parameter — is undocumented in both schema and description, leaving its source (presumably list_pending_proposals) to inference.

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

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

States a specific verb (reject) applied to a specific resource (pending proposal) plus the concrete effect: 'so it will never execute.' An agent can immediately distinguish it from the sibling approve_proposal without opening either schema.

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

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

Gives an explicit trigger: 'Use when: the user says no to a proposed change.' The natural alternative (approve_proposal) is not named, so the routing is clear but not exhaustive.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds context beyond them: cost is free and not counted against tasks, the result includes risk/cost/arguments and an exact 'How to call' line, most tools go through a platform router, and delete requests get a special note because no tool performs them. This is unusually rich behavioral disclosure.

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

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

Front-loaded with a cost/safety tag and a one-line purpose before the Use when / When not / Returns structure, so an agent can scan it quickly. It is longer than strictly necessary — the returns paragraph and the delete note could be tightened — but each block carries distinct routing 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?

There is no output schema, and the description compensates fully by describing the returned rows and the 'How to call' line, plus a failure-mode instruction to report no match and ask the user rather than invent a tool. Nothing needed to invoke it correctly is missing.

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 query, top_k, platform and raw_data including enum values and defaults. The description restates the cross-platform default ('Searches every platform unless you pass platform') but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Finds the tools that do a job, ranked') and the input basis ('from the user's own wording'). It explicitly differentiates itself from the sibling get_tool_schema by naming what that tool does that this one doesn't.

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?

Has explicit 'Use when' triggers (unknown tool, user asks for something unseen, guessed name came back unknown) and an explicit 'When not to use' that routes to the correct alternative (call the known tool, or get_tool_schema for arguments). Nothing is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the description is not the primary source of safety info. It nonetheless adds genuinely new context: cost is free and not counted against tasks, and it warns the agent not to attempt platform tools when nothing is connected. That is real behavioral value beyond 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?

Front-loaded with the classification header ('READ-ONLY... free'), then purpose, then the 'When not to use' block. Every sentence carries information an agent needs; nothing is redundant padding.

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

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

With no output schema present, the description steps in to describe the return contents (platforms, accounts, primary account, remaining tasks, example prompts with cost), and it covers the failure mode of no connections. Nothing material is missing for a zero-required-parameter bootstrap 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?

There is a single optional parameter (raw_data) and schema description coverage is 100%, so the schema already explains it fully. The description adds nothing about parameter syntax or format. Per the high-coverage baseline, a 3 is appropriate.

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

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

States a specific verb and resource ('Returns the real state of this user's Adako account') and enumerates the concrete payload: connected platforms, active/primary accounts, remaining tasks, and example prompts with cost. Adjacent siblings like get_connections_status and list_connected_accounts are implicitly differentiated by the broader account-state scope plus the 'call first' framing.

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 states when to call ('first in a new conversation, or whenever you are unsure what the user can do'), when not to ('you already know the connection state from an earlier call'), and the fallback action when nothing is connected. Both inclusion and exclusion conditions are spelled out.

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?

Goes well beyond annotations by disclosing that the target is switched on if inactive, that other active accounts stay active, that the previous primary is switched off to make room when the plan limit would be exceeded (and stays connected), and that otherwise it fails with account_limit. Also clarifies that nothing changes on the ad platform, so no proposal is created.

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

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

Front-loaded with a WRITE marker and cost line, then behavior, use-when, and not-for. Dense but every section carries distinct information; slightly long but no clearly wasted sentence.

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 no output schema, the description covers the side effects, the plan-limit failure mode (account_limit), and the absence of platform-side changes. An agent has everything needed to invoke it correctly and interpret the outcome.

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 75%; account_id and idempotency_key/raw_data are documented in the schema itself. The description reinforces that the account must be known to Adako but adds no new syntax or format detail beyond what the schema provides, fitting the baseline 3 for adequate-but-not-additive parameter guidance.

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

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

States a specific verb+resource ('Makes one account the primary account for its platform') and clarifies its downstream effect ('the one later tools use when no account id is passed'). This distinguishes it from all sibling account-management 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?

Includes an explicit 'Use when' (user says 'use account X from now on', or account_ambiguous/not_connected after confirmation) and an explicit 'Not for' (manager accounts, which hold no campaigns), plus a prerequisite (account must be known to Adako, see list_connected_accounts).

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description reinforces 'nothing called here changes anything'. It adds context beyond the annotations: reads are free, execute bills the underlying tool, and the write half lives in a separate router. It does not, however, say what execute returns or how cost is metered, so it stops short of a 5.

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

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

Front-loaded with the one-line contract and the free-vs-billed rule before the category inventory. The 18-tool category dump is long but functional for a router that must disclose what sits behind it. Slightly heavy, but little is wasted.

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 passthrough router with no output schema, the description covers routing, billing, account fan-out, the escape hatch to the write router, and the full tool inventory. The one gap is the return shape of execute, which an agent could reasonably want, though the tool's own schema is reachable via get_tool_schema.

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 goes further: it explains that action='execute' incurs the underlying tool's billing, that list_tools/get_tool_schema are free, that accounts is a read-fan-out capped at 20, and warns that tool_name must come from lookup rather than guessing. That is genuine meaning added on top of the schema text.

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 exactly what it is — reads plus tool lookup for TikTok Ads — and explicitly carves off the write half ('12 tools that change something run through tiktok_ads_write'). An agent can distinguish this router from tiktok_ads_write and the *_get_campaign_performance siblings without opening a schema.

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

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

Routing is fully specified: action=list_tools/get_tool_schema are free, 'never guess a tool_name', execute requires tool_name+arguments, accounts accepts a list or "all_active" capped at 20. It also names tiktok_get_campaign_performance as called by name rather than through the router, which is real alternative-selection 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 declare destructive/write/non-idempotent, but the description adds behavior they cannot express: every call creates a proposal the user must approve before anything changes, creates are PAUSED, and it is one account per call with no fan-out. Those are exactly the traits an agent needs to plan a write safely.

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

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

Front-loads the routing distinction and invocation signature, then organizes the 12 sub-tools by category, so every block is scannable. Slightly redundant in the opening ('not here — that is tiktok_ads … always wrong') repeats the same point twice.

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 router with nested arguments and no output schema, the description covers routing, invocation shape, approval gating, account scoping, and the full inventory of sub-tools. Nothing needed to call it correctly is missing.

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 properties already document action='execute', tool_name, and the nested arguments object. The description reinforces the dispatch pattern but adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource class: the write-side router for the 12 TikTok Ads tools that create, update, pause or remove. It explicitly distinguishes itself from its read sibling, tiktok_ads, so an agent can route without opening either schema.

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

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

Gives both when-to-use and when-not: reads/listings/checks belong to tiktok_ads, and using this router for a lookup is 'always wrong'. It also names the alternatives (tiktok_ads and tiktok_ads(action="get_tool_schema") for free schema lookup), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds material context: cost ('free, not counted against tasks'), data-settling lag, that presets end yesterday, and the default comparison behavior. It even explains output semantics (a dash means the prior period was zero) that no structured field covers.

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

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

Front-loaded with the safety/cost line and the purpose, then scoping, then exclusions, then interpretation guidance. It is on the long side and the hook/hold/completion coaching is close to advice rather than tool definition, but each sentence carries actionable information.

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

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

With no output schema and eight parameters, the description compensates by explaining what is returned (spend, video metrics, ratios) and how to read it, plus fallback behavior for all-zero results. An agent can call and interpret this tool without further 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 coverage is 100%, so the schema already documents all eight parameters, but the description adds real meaning: campaign_id scoping behavior, that presets end yesterday to avoid partial days, and the reasoning behind the comparison default. It stops short of covering date versus custom-range exclusivity beyond what the schema states.

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

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

States a specific verb and resource ('Reports spend, impressions, reach, clicks, conversions and the TikTok video metrics ... per campaign') and names scope behavior ('without it you get every campaign'). It is clearly distinguishable from the sibling generate_report_now and from tiktok_list_ads, which it references by name.

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?

Explicit when-to-use ('the user asks how TikTok is doing, whether something is working, or what changed') and when-not ('Do not use it for a brief or a report to keep or forward: that is generate_report_now'). It also gives a methodological exclusion ('Do not read a single day and call it a trend') with the preferred alternative preset.

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