Mako Metrics

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

Annotations only mark it non-read-only, open-world, non-destructive; the description goes well beyond by stating the campaign cannot deliver or spend until manually activated, that it takes a minute or two, and the exact budget floors and ceiling. This is exactly the behavioral context an agent needs for a mutation that costs money.

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 purpose, then the paused/behavioral safety point, then budget limits and prerequisites. Every sentence carries information, though the 'which this tool cannot do and neither can any other' clause is slightly verbose.

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 an 8-parameter mutation with no output schema, the description covers safety, cost constraints, and prerequisites well. It omits what the tool returns (e.g., a campaign ID) and does not explain bid_strategy/bid_amount interaction, so it is strong but not fully complete.

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

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

Schema coverage is 63% and the description meaningfully enriches two key parameters: budget floors ($6/day for leads and sales, $1/day otherwise; $500/day ceiling) add constraints the schema lacks, and the leads/sales requirement ties to conversion_asset_id and goal. It does not address bid_amount/bid_strategy semantics, leaving a gap.

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

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

Specific verb+resource: 'Build a real Meta campaign from chosen concepts, in the client's own ad account, left PAUSED.' It clarifies scope (client's own account, from chosen concepts) and the critical state (paused), letting an agent distinguish it from sibling list/draft tools 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?

States concrete prerequisites (needs the May plan, a connected Facebook ad account, an X-Mako-Key header) and clarifies the boundary that activation must happen manually in Ads Manager, which no tool can do. It lacks an explicit 'use this instead of X' comparison, but no close sibling alternative exists, so context is clear.

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

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

Annotations only disclose the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond them by disclosing the quota model (plans include a fixed number of active clients), the quota-exhaustion failure mode, and required authentication/plan prerequisites — exactly the mutation context an agent needs before invoking.

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

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

Three short sentences, front-loaded with the action, then domain context, then prerequisites and failure mode. No sentence is redundant and nothing is buried.

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 one-parameter mutation with annotations covering safety, the description covers prerequisites, quota limits, and failure behavior. The only gap is that with no output schema it never indicates what a successful call returns (e.g., a new client identifier), which an agent would need to chain a follow-up call.

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 there is a single parameter, so the schema already carries the naming guidance ("as the customer would say it"). The description adds domain framing — that a workspace maps to one brand — but no syntax, format, or validation 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?

The first sentence names a specific verb and resource ("Add a client workspace to the account"), and the second sentence clarifies what that resource contains, which removes ambiguity about the domain object. It does not explicitly contrast itself with any sibling such as list_clients or order_report, so it lands at clear-but-undifferentiated.

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

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

The description states concrete preconditions for use ("Needs the May plan and an X-Mako-Key header") and a failure condition ("fails when the roster is full"), which is stronger than generic context. It stops short of naming alternatives or when-not-to-use guidance, so it is not 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 only say readOnlyHint=false/openWorld=true/destructiveHint=false; the description goes far beyond by disclosing that no payment is captured, that it only emits a link a human opens, the post-payment email timing (~24h), and what the customer ultimately downloads. This is the behavioral context an agent cannot get 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-loaded with the core action and return value, and each sentence carries weight (payment behavior, delivery, plan restriction, May exception). The portal/download sentence is informational but slightly over-detailed for tool selection purposes.

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 9-param, no-output-schema, open-world creation tool, the description covers what is created, what is returned, and what happens afterward, which is the critical missing piece. It leaves gaps on parameter expectations (especially the required unlabeled enums and optional fields) but nothing that blocks correct invocation.

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

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

Schema coverage is only 33% across 9 params, so the description must compensate and largely does not: it explains nothing about revenue_band, industry_vertical, company_name, company_website, or notes, and only lightly constrains 'plan' via 'Report plans only'. Competitor limits and the email purpose are already in the schema, so the description adds little param-level meaning.

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

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

States a specific verb+resource ('Create a Mako Metrics order brief') and immediately defines the return ('a Stripe checkout link'), which is exactly what an agent needs to distinguish this from siblings like order_report or list_plans. It does not explicitly name a sibling or state the boundary with order_report, so it stops just short of a 5.

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 a clear usage constraint ('Report plans only') and an explicit alternative route for a different case ('For May, the Meta ads agent, send the customer to makometrics.com/meta-ads-agent'), which is genuine when-not guidance. No prerequisites or preconditions (e.g., what must exist first) are stated, so it falls 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 mark it as non-destructive, open-world, and not read-only. The description adds important context beyond annotations: it takes up to a minute or two, the result is a draft requiring review, and it needs the May plan plus an X-Mako-Key header. This gives an agent practical expectations about duration and authentication.

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 front-loads the purpose, then adds timing, draft status, workflow, benefit, and auth in compact sentences. Each sentence mostly earns its place, though the 'fastest way' line is slightly promotional rather than strictly behavioral.

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-parameter drafting tool with annotations and no output schema, the description covers purpose, duration, draft outcome, the necessary follow-up tools, and authentication needs. Nothing an agent must know before calling it 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 both parameters (website_url and client_account_id) are already documented. The description only implicitly ties the tool to a client's website; it adds no format or constraint details beyond the schema, so 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 verb and resource: reads a website to fill in a brand profile automatically. It distinguishes the tool from siblings by naming the review (get_brand_profile) and correction (set_brand_profile) steps. An agent can immediately tell this is a drafting tool, not a final profile setter.

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

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

Explicitly says to review with get_brand_profile, correct with set_brand_profile, and confirm, and calls this the fastest way to prepare a new client for a May run. It lacks an explicit when-not-to-use condition, but the workflow context is clear enough to guide selection.

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 openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the auth requirement (X-Mako-Key header) and the conditional return behavior (confirmation status plus the specific missing answers).

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

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

Two tight sentences, front-loaded with the resource and its contents, followed by the readiness-check behavior and the auth requirement. No filler.

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

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

For a read-only tool with no output schema, the description sufficiently explains what is returned (profile fields, confirmation status, missing answers). 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% and the single parameter's origin ('From list_clients') is already documented in the schema. The description adds no syntax or format detail beyond it, so the baseline of 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 ('Read') and resource ('brand profile'), then enumerates the exact contents (what they sell, who buys it, voice, colors, campaign defaults). This clearly distinguishes it from set_brand_profile and list_clients.

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 a concrete usage context: checking whether a profile is confirmed and which answers are still missing before May can run. It also names the required X-Mako-Key header, which tells the agent a precondition. It does not explicitly name alternatives, but the use case is clear.

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

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

Adds behavior annotations do not carry: the link expires after 10 minutes and the call requires an X-Mako-Key header. Expiry and auth requirements are exactly the sort of context an agent needs and cannot infer from readOnlyHint/openWorldHint. The 'mint' verb sits in mild tension with readOnlyHint, but generating an ephemeral URL does not modify stored state, so it is not a genuine contradiction.

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

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

Two sentences, no filler, and the most important constraint (short-lived link) is front-loaded right after the purpose.

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 one-parameter tool with no output schema, the description covers purpose, auth, and expiry. It only lightly implies that the return value is the URL itself rather than naming the returned field, which is a minor gap.

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

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

Schema description coverage is 100% and the single parameter is documented ('From list_deliverables'), so the schema already does the work. The description adds no further parameter detail; 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: 'Mint a download link for one deliverable.' An agent can distinguish this from list_deliverables (which supplies the id) and from the other siblings, which operate on brands/clients/orders.

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 clear timing guidance and an explicit exclusion: 'fetch it when the human is ready to use it rather than in advance.' The schema note 'From list_deliverables' implies the required prior step, but no alternative tool is named for comparison.

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 and closed-world scope, but the description adds real behavioral context: it requires an X-Mako-Key header (auth) and describes what the response contains (status, and a deliverable id once finished). No contradictions with annotations.

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

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

Three tight sentences with no filler, front-loading the primary action and mode, then the return value, then the auth requirement. Every sentence earns its place.

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

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

With no output schema present, the description carries the return-value burden and does so (status plus deliverable id), and it notes the required header. 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 description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the id semantics (report request id or May run id) and the omit-to-list behavior, but adds little beyond what the schema states — 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 ('Check') and two concrete resources ('one report order or one May run'), plus the dual-mode behavior (by id vs. list recent). An agent can distinguish this from siblings like list_deliverables or order_report 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?

Explicitly states the two modes — pass an id to check one item, omit it to list the most recent of both — and routes the agent forward to get_download_url once finished. It does not name a condition under which this tool should be avoided, so it falls short of a full 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: the required X-Mako-Key auth header and the meaning of one returned field (brand profile readiness for a May run).

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?

A single front-loaded sentence that covers scope, return value, and auth requirement with no filler. Every clause earns its place.

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

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

With no output schema, the description carries the burden of hinting at the return shape, and it does so (client IDs plus brand-profile readiness). For a zero-parameter read-only list tool, this is sufficient 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?

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it does not pad with irrelevant parameter talk.

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 ('List the client workspaces on this account') and even previews returned fields, which distinguishes it from sibling list_* tools (list_creatives, list_deliverables, list_plans). It does not explicitly name which sibling it is not, so it stops short of a 5.

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

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

The phrase 'with the id each other tool needs' clearly frames this as the discovery/entry-point call that feeds create_client, get_brand_profile, run_may, etc., giving real usage context. However, it states no exclusions or conditions under which you would skip it.

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral context the annotations do not: each concept is deduplicated to its newest version, and the call requires an X-Mako-Key header. It omits pagination/rate-limit behavior, keeping it from 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?

Three short sentences, front-loaded with the purpose and returned fields before the downstream usage note and the auth requirement. Every sentence carries information the caller needs.

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 one-parameter read-only tool with no output schema, the description usefully enumerates the return payload (headline, primary text, CTA, compliance status, download link), the deduplication rule, and the auth header. The only omission is any mention of result size or pagination, which is minor here.

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

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

With a single parameter at 100% schema description coverage, the schema already documents run_id including its origin (get_status or run_may), so the description adds nothing there. It mentions variant_id, but that is an output field, not an input, which slightly muddies rather than clarifies parameter semantics.

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

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

States a specific verb (List) and resource (ad concepts from a May run) and enumerates the returned fields, so an agent can distinguish it from list_meta_assets and list_deliverables without opening the schema. The addition of 'Returns the newest version of each concept' pins down the returned scope precisely.

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 clear context (use the output's variant_id values with build_paused_campaign) and the schema ties run_id to get_status or run_may, which is genuine routing guidance. It does not, however, state when this tool should NOT be used instead of a sibling list tool, so it stops short of full alternative coverage.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful context — the X-Mako-Key auth requirement and the fact that only completed deliverables are returned — but says nothing about ordering, pagination, or result shape.

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

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

Two tight sentences with the scope front-loaded before the auth note; no filler. It could be marginally sharper by folding the auth requirement into a usage clause, but it is well sized for the operation.

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 read-only list tool with no output schema, the description conveys what is returned at a high level and the auth prerequisite. It stops short of paging/limit behaviour and the client-account scoping, which an agent calling it with three optional params would benefit from knowing.

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 33%, so the description must compensate. It loosely maps the kind enum values (competitor report bundles, May run artifacts) but adds nothing for limit and never explains the client_account_id narrowing, so half the parameters remain opaque in both description and 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 (List) and resource (deliverables) and enumerates the two content types returned: competitor report bundles and May run artifacts. It does not, however, explicitly contrast itself with adjacent siblings such as get_download_url or order_report, so an agent must infer the boundary.

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 says what is listed ('finished and ready to download') but never states when to call this versus get_download_url (the obvious next step) or order_report/run_may (which produce the artifacts). There are no stated conditions or exclusions, only implied usage.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior context beyond that: the required X-Mako-Key header and the human-in-the-portal constraint for connecting Facebook. It stops short of describing what happens when no account is connected, but the added operational detail is above the annotation baseline.

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

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

Three sentences, each earning its place: purpose first, then call ordering/why, then the prerequisite and auth requirement. No filler and the most important information is front-loaded.

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

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

For a read-only lookup with no output schema, the description covers purpose, ordering relative to build_paused_campaign, the human prerequisite, and auth. Minor gaps remain (e.g., behavior when no Meta account is connected), but 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% and the single parameter is already documented as 'From list_clients.' The description adds no further meaning about client_account_id, so the baseline of 3 applies 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?

States a specific verb ('Show') and resource ('the client's connected Facebook ad account and the conversions available to optimize toward'), which is concrete enough to distinguish it from siblings like list_clients or list_creatives. An agent knows exactly what it retrieves 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 names when to call it ('before build_paused_campaign on a leads or sales campaign') and why ('those need a conversion to aim at'). It also states the out-of-band prerequisite that connecting Facebook has to be done by a person in the portal, which routes the agent away from trying to do it programmatically.

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?

readOnlyHint=true and openWorldHint=false already establish this as a safe, closed-world read. The description adds useful framing ('the only products orderable through this server', plans include merchant-verification links), but says nothing about pagination, caching, or freshness of pricing data, so it stays at the lower bar set by the annotations.

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

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

Three sentences, front-loaded with the core action and result contents. Every sentence carries information (contents, use trigger, scope/exclusion), though the final May sentence is somewhat tangential to listing plans.

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 no-parameter read tool with no output schema, the description adequately previews the returned fields (pricing, inclusions, scope, delivery, guarantee, links) and the domain boundary. Only the lack of any count/format expectations keeps it from full completeness.

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

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

The tool takes no parameters and the schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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

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

Specific verb and resource ('List Mako Metrics plans') followed by an enumeration of what the listing contains: pricing, inclusions, scope limits, delivery, guarantee, and merchant-verification links. This is enough to distinguish it from siblings like order_report or list_deliverables 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?

'Use this to recommend a plan before ordering' gives a clear trigger point. It also scopes the tool ('competitor report plans... the only products orderable through this server') and routes the May agent engagement out to makometrics.com/meta-ads-agent, but it does not name a sibling tool as a direct alternative, so it stops short of the top tier.

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?

Despite annotations only flagging readOnlyHint=false and destructiveHint=false, the description discloses the async human-built workflow, ~24-hour delivery to the portal, plan-dependent billing behavior, and the required X-Mako-Key header. This is exactly the behavioral context beyond structured fields that the dimension rewards.

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?

Five tight sentences, front-loaded with purpose, then plan behavior, async expectations, polling path, and auth. Every sentence conveys actionable 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?

For a mutation tool with no output schema, the description covers billing, async timing, follow-up tools, and authentication, so an agent has everything needed to invoke and track it correctly. Annotations and schema gaps are fully compensated.

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 63% with 8 parameters, so the schema carries much of the load. The description clarifies the single-competitor constraint and goal context but adds no per-parameter syntax or format detail beyond the schema; 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 verb and resource ('Order a competitor Meta ads report') with a scope constraint ('for one competitor'). An agent can distinguish this immediately from siblings like create_order or list_deliverables.

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 describes when the tool spends an allowance versus returns a Stripe checkout link (Dominator/Agency/May vs Snapshot), and names the follow-up tools (get_status, then list_deliverables). Nothing about selection or sequencing 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?

Beyond the annotations, it discloses duration (a few minutes, up to ~20 minutes in 'researching' state), what side effects occur (creative built plus a PAUSED campaign), explicit non-effects ('never turns anything on and never spends ad budget'), and auth/plan requirements ('Needs the May plan and an X-Mako-Key header'). This is rich behavioral context that 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?

The purpose and deliverable are front-loaded in the first sentence, and subsequent sentences each add distinct value (duration, non-effects, prerequisites). It is somewhat dense and could tighten the repeated 'portal' references, but nothing is 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?

With no output schema, the description must carry the full burden, and it does: it explains what is produced, where it lands (the portal), the observable status, timing, safety posture, and required auth. An agent has everything needed to invoke 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 coverage is 80%, so the schema already documents brief, avoid, feature, objective, and client_account_id. The description adds no per-parameter syntax or format guidance, so the baseline 3 for high schema coverage 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?

The description states a specific verb and resource ('Start a May creative run') and enumerates the deliverables (research, copy, eight ad concepts). It distinguishes itself from siblings like build_paused_campaign by clarifying that May builds creative and separately a paused campaign.

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 a clear prerequisite ('client needs a confirmed brand profile first, which is filled in at makometrics.com/portal') and implies the research-before-run path when a competitor is named. It never explicitly names alternative tools (e.g. set_brand_profile, list_clients) for the unprepared case, so it stops short of full when/when-not routing.

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?

Adds substantial behavior beyond the annotations: merge/patch semantics ('only what you pass is changed'), idempotent-safe framing, the confirm gate and exactly which fields confirming requires, plus auth requirements (May plan, X-Mako-Key header). Annotations only cover the safety profile, so this carries real extra weight.

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 core action and merge semantics, then the confirm gate and prerequisites. Five dense sentences with no filler; every clause carries information an agent needs before calling.

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 28-parameter mutation tool with no output schema, the description covers the gating logic and prerequisites well. It leaves the response behavior and the semantics of less obvious fields (notes, price_range, competitor_websites interplay) unaddressed, but nothing critical to a correct call 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 already 75%, and the description supplements it by explaining confirm's gating behavior and the six-plus fields required for confirmation, which the schema only marks as optional. The remaining undocumented params (notes, category, price_range, website_url, support_email) get no help, so it stops short of full compensation.

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 ('Write or update one client's brand profile') and scopes it to a single client. It implicitly separates itself from the read sibling get_brand_profile and the generator draft_brand_from_website by framing itself as the corrector of a website draft, but it never names those siblings 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?

Gives clear operational context: safe to call repeatedly for corrections, and pass confirm:true when answers are final because run_may depends on it. It also lists the prerequisites (May plan, X-Mako-Key header). It stops short of explicitly routing the agent to get_brand_profile for reads or draft_brand_from_website for initial drafts.

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 openWorldHint=false, so safety is covered. The description adds valuable behavioral context beyond the annotations: it names the required X-Mako-Key header, its origin (makometrics.com/portal), and the account-scoping behavior of the key. It doesn't discuss rate limits or failure modes, keeping it from 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?

Three sentences, all front-loaded: purpose and return fields first, then the ordering instruction, then the authentication requirement. No filler; each sentence carries distinct, necessary 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?

For a no-arg read tool with a clear annotation profile, the description covers purpose, return contents, usage timing, and auth requirements well. The absence of an output schema means field-level formatting isn't specified, but the described fields give an agent enough to proceed.

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

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

Zero parameters, so the baseline is 4. The description goes further by documenting the implicit X-Mako-Key header requirement, which is not represented in the schema but is essential to invoking the tool correctly.

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 ('Show') and resource (the account a key belongs to), then enumerates the exact returned fields: plan, remaining competitor reports, and client workspaces. This distinguishes it from siblings like list_clients or list_plans, which return narrower resources.

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

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

Explicitly says 'Call this first in any session that will use the customer tools,' giving a clear when-to-use rule and establishing it as a prerequisite/alternative to the other account-related tools.

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