Mako Metrics

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

With no annotations provided, the description carries the full behavioral burden and does it well: it discloses that the campaign is created paused, cannot deliver or spend, takes a minute or two, and has budget floor/ceiling constraints. It does not describe the return format or error behavior, but the essential live-account safety traits are clearly stated.

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

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

The description is one tight paragraph with all sentences earning their place. The key purpose is front-loaded, followed by constraints and prerequisites. Minor redundancy exists in 'which this tool cannot do and neither can any other,' but overall it is efficient for an 8-parameter tool.

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

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

For a complex creation tool with no annotations and no output schema, the description covers safety and prerequisites but omits important operational details: what the response contains, how bid_strategy relates to bid_amount, and how to choose among parameter combinations. It is adequate but leaves an agent with meaningful gaps.

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

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

The description adds meaningful parameter context beyond the schema by explaining budget floors tied to goal type and the $500/day ceiling, which enriches daily_budget and goal. It also indicates run_id comes from a 'May plan.' However, it leaves bid_amount, bid_strategy, campaign_name, and conversion_asset_id semantics mostly to the schema, and the schema coverage is moderate.

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: 'Build a real Meta campaign from chosen concepts, in the client's own ad account, left PAUSED.' It clearly differentiates this from sibling tools like list_creatives or run_may, and the paused-delivery constraint is prominent.

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

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

The description gives clear context for when the tool is appropriate: it requires a May plan, a connected Facebook ad account, and an X-Mako-Key header. It also states that unpausing cannot be done by this tool or any other, which sets expectations. However, it does not explicitly contrast this tool with alternatives like run_may or list_meta_assets.

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?

With no annotations, the description carries the burden and it delivers: it discloses a failure condition (roster full) and a prerequisite (May plan + header). It doesn't mention return values or idempotency, but it covers key side effects and constraints well for a simple create operation.

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?

Four sentences, no fluff. The core action is front-loaded, and the subsequent sentences add valuable context (workspace contents, plan limits, header requirement). It is concise without omitting important operational details.

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

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

For a tool with a single parameter and no output schema, the description covers the essential context: purpose, what the workspace contains, failure mode, and prerequisites. It could mention the return value, but that is minor given the tool's simplicity.

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 schema fully describes the 'name' parameter. The description adds no additional parameter meaning beyond the schema, so the baseline of 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?

The description clearly states the action ('Add a client workspace'), the resource, and what it contains ('brand's profile, runs, creatives and campaigns'). This differentiates it from sibling tools like create_order or draft_brand_from_website, making the purpose unambiguous.

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

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

Provides strong context for usage: prerequisites ('Needs the May plan and an X-Mako-Key header') and a failure condition ('fails when the roster is full'). It does not explicitly name alternatives or state when NOT to use it, but the context is clear enough that an agent can infer when this tool is appropriate.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool does not take payment, that it returns a Stripe checkout link, and that after payment the customer gets an email within 24h and can download reports at a specific portal link. It is transparent about the post-payment workflow and what happens offline. It does not detail any side effects or failure modes, but the core behavioral disclosure is strong.

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

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

The description is concise (three sentences plus a note about May) and front-loaded with the primary action. Every sentence adds value. However, the last sentence ('For May, the Meta ads agent...') could be restructured or moved to a separate usage note, but it does not detract significantly. It earns a 4 for being efficient and well-organized.

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

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

Given the tool has 9 parameters, 6 required, no output schema, and moderate complexity (enums, array input), the description provides enough context to understand the purpose and workflow. It explains the output (Stripe link), the post-payment process, and the portal location. It does not describe the return format or handle failure cases, but for a creation tool that returns a link, the description is reasonably complete.

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

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

Schema description coverage is 33% (only email, competitors, and client_account_name have descriptions). The tool description does not add parameter-level guidance beyond what is in the schema. The description does not help interpret enum values (plan, revenue_band, industry_vertical) or the purpose of notes, company_website, etc. However, the description provides high-level context for what the order is, which indirectly helps understand 'plan' and 'competitors'. Baseline 3 is appropriate because the schema carries the burden and the description does not significantly compensate for the low coverage.

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 explicitly states the verb 'Create a Mako Metrics order brief', identifies the resource ('customer order'), specifies the outcome ('return a Stripe checkout link'), and distinguishes the tool by noting it does not take payment. It also provides specific context for the sibling tool 'list_plans', which is likely a prerequisite, and addresses a separate use case for 'May, the Meta ads agent'.

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 clearly states when to use this tool ('Create a Mako Metrics order brief for a customer') and what it does not do ('No payment is taken by this tool. It only returns a pay link the human opens.'). It gives an explicit alternative use case ('For May, the Meta ads agent, send the customer to makometrics.com/meta-ads-agent') and implies the agent should not attempt payment or download—only create the brief and return the link.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses that the operation reads an external website, may take up to a minute or two, and produces only a draft rather than a final result. It also states the required header and plan. It could add whether existing profile data is overwritten, but the draft framing implies non-destructive intent.

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

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

The description is compact yet information-dense. Every sentence contributes: what it does, time expectation, draft status and follow-up workflow, use case, and prerequisites. The key action is front-loaded, and there is no redundant 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 there is no output schema and no annotations, the description covers the essential operational context: purpose, duration, draft nature, follow-up tools, and required preconditions. It does not explain exactly what fields get filled or how confirmation works, but the guidance is sufficient for an agent to invoke the tool and continue the workflow.

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

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

The input schema already provides 100% coverage of both parameters, describing website_url as the homepage and client_account_id as coming from list_clients or create_client. The description adds little parameter-specific meaning beyond 'client's website' and reinforces client context. Baseline 3 is appropriate since 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 clearly states the tool's function: read a client's website and automatically fill in most of their brand profile. It also distinguishes the output as a draft, setting expectations against the sibling set_brand_profile. This is a specific verb+resource combination with no ambiguity.

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

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

The description gives clear context: this is the fastest way to get a new client ready for a May run, and it must be followed by review and correction using get_brand_profile and set_brand_profile. It does not explicitly list when not to use it, but the workflow and prerequisites (May plan, X-Mako-Key header) are stated. This is clear context without formal exclusions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds the auth requirement ('Requires an X-Mako-Key header'), states that the tool reports confirmation status and missing answers, and 'Read' conveys that this is a non-mutating operation. It does not cover error behavior, but the key behavioral detail is present.

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 dense sentences with no filler. The action and object are front-loaded, and each clause earns its place by specifying content, readiness semantics, or auth requirements.

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

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

For a simple one-parameter read tool with no output schema, the description covers what will be returned, the input source, the auth header, and the relation to run_may. It does not describe error responses or pagination, but those are minor for this tool's complexity.

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% for the single parameter, which is already described as 'From list_clients.' The description adds no additional parameter-level meaning, so the baseline score 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?

The description opens with 'Read one client's brand profile,' naming a specific verb, resource, and scope. It further enumerates the contained fields (what they sell, who buys it, voice, colors, campaign defaults) and distinguishes itself from siblings like set_brand_profile and draft_brand_from_website.

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

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

The description gives a clear usage context: check a client's brand profile and see which answers are still missing before May can run. It does not explicitly name alternatives or state when not to use it, so it falls short of a perfect 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?

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the 10-minute expiration, the need to avoid fetching early, and the required authentication header. It does not mention whether any persistent state changes occur, but for a link-minting tool these traits are meaningful and useful.

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

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

Two sentences with no filler. The purpose is stated first, followed by the critical timing behavior and 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?

For a simple one-parameter tool with no output schema, the description is complete enough to invoke correctly: it explains what the tool does, when to call it, and what authentication is required. No critical information 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, deliverable_id, is already described as coming from list_deliverables. The main description adds little beyond that, so the baseline score 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?

The description uses a specific verb and resource: 'Mint a download link for one deliverable.' It clearly distinguishes this tool from siblings like list_deliverables or create_order by making the output (a temporary link) and scope (one deliverable) explicit.

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

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

It provides clear usage context: fetch the link only when the human is ready to use it, because it expires in 10 minutes. It also states the required X-Mako-Key header. It does not explicitly name alternatives or exclusion criteria, but the timing guidance is strong.

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?

No annotations are provided, so the description carries the full burden. It discloses the required X-Mako-Key header, the optional-id behavior, the return contents (status and deliverable id), and the asynchronous 'once finished' nuance. It does not mention pagination, limits, or side effects, but for a status-check tool the key behaviors are covered.

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 and behavior, return value plus downstream handoff, and authentication requirement. The key information is front-loaded and there is 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 two-parameter tool with no output schema and no annotations, the description is quite complete: it covers the two modes of use, the return value, the downstream tool, and an auth requirement. It could be more explicit about what 'most recent of both' returns structurally, but the essential call-and-response logic is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context that the id corresponds to either a report order or a May run, but the schema already says this. The client_account_id parameter's meaning is fully covered by the schema and adds nothing beyond it in the description.

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 action ('Check') with a clear resource ('one report order or one May run by its id'), and distinguishes the omitting-id listing behavior. It also explicitly routes the returned deliverable id to get_download_url, setting it apart from siblings like list_deliverables and get_download_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?

The description gives clear conditions for use: provide an id for a single status check, or omit it to list the most recent items. It also indicates the follow-up tool (get_download_url). It does not explicitly discuss when not to use the tool versus list_deliverables or other siblings, but the main usage 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?

With no annotations, the description carries the full disclosure burden. It reveals authentication requirements, the account scoping, and the two key pieces of returned information. For a parameterless list operation, this is sufficient; pagination and error behavior are not documented but are not critical here.

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

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

The description is a single, compact sentence that front-loads the purpose and packs in the essential scope, output details, and authentication requirement. No words are 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 simple parameterless list tool with no output schema, the description covers the required auth headerable, the scoped resource, and the meaningful return values. It does not specify exact field types or pagination, but nothing prevents an agent from invoking and understanding the result 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?

The schema has zero parametershare, so there is nothing for the description to clarify beyond the schema. The baseline of 4 applies, and the description usefully focuses on the output fields rather than parameters.

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

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

The description clearly states the action ('list'), the resource ('client workspaces'), and the account scope. It also differentiates itself from sibling list tools by specifying the returned id and the brand-profile readiness flag for a May run.

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

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

The description gives useful context: the returned id is what other tools needable for subsequent calls, and the brand-profile readiness flag relates to a May run. It also notes the required X-Mako-Key header, but it does not explicitly state when not to use this tool or name 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that an X-Mako-Key header is required, that only the newest version of each concept is returned, and that downloadable image links are included. It does not describe pagination or error behavior, but the core behavioral traits are covered.

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

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

The description is three tight sentences with no filler: first the return contents, then the versioning behavior, then the downstream usage and auth requirement. Each sentence earns its place and the most useful 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 single-parameter list tool with no output schema, the description covers the return fields, versioning, downstream usage, and authentication. The only minor gap is that variant_id is referenced in the usage guidance but not explicitly listed among the returned fields, though the context makes it clear it is part of the output.

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 for the single parameter run_id is 100%, and its description already explains where the id comes from (get_status or run_may). The tool description adds no additional meaning to the parameter, so the baseline of 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?

The description names a specific verb and resource ('List the ad concepts from a May run') and enumerates the returned fields: headline, primary text, call to action, compliance status, and image download link. This makes its purpose unmistakable and distinguishes it from sibling list tools like list_meta_assets or list_deliverables, which target different 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?

The description gives clear usage context: it is for retrieving ad concepts from a May run, and it explicitly instructs the agent to use the resulting variant_id values with build_paused_campaign. It does not explicitly name alternatives or state when not to use this tool, but the context is strong 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?

With no annotations, the text must carry the behavioral burden; 'List' signals a read-only operation and the X-Mako-Key requirement adds useful auth context. It does not mention pagination, response shape, or that results can be narrowed by the optional filters.

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 clean sentence front-loads purpose and scope, then adds the auth requirement without any filler. Every phrase 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 simple optional-filter list tool, the description plus schema covers the core: what is listed, account scope, and required auth. But without an output schema or annotations, the agent still lacks return-shape and pagination context, and the description's 'everything' doesn't signal the available filters.

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 low at 33%, so the description should compensate. It adds real meaning to 'kind' by mapping it to 'competitor report bundles and May run artifacts', and 'account' loosely maps to client_account_id. The limit parameter, however, gets no semantic enrichment beyond its schema min/max.

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'), a specific resource ('everything finished and ready to download'), and the account scope. By naming 'competitor report bundles and May run artifacts', it clearly separates this from siblings like get_download_url 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?

The description implies the right scenario—enumerating finished deliverables on the account before downloading—and adds an important auth requirement. However, it does not explicitly say when to prefer this over get_download_url or exclude other sibling 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?

No annotations are provided, so the description carries the full burden. It discloses the auth header, the prerequisite of manual connection, and implies a read-only nature by saying 'Show'. It does not explicitly state that no data is modified, but the verb 'Show' strongly implies it, and there is no contradiction. The description adds context beyond what annotations would provide.

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

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

Two sentences with zero waste. The purpose is front-loaded, followed by precise usage guidance and prerequisites. Every sentence earns its place, and the structure is clean 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?

For a single-parameter read tool with no output schema, the description fully explains what it returns (ad account and conversions), when to call it, the prerequisite, and the auth requirement. 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% because the parameter has a description ('From list_clients.'). The tool description does not add further parameter meaning beyond that, but the schema already provides the source of the value. Baseline 3 is appropriate since the schema carries the parameter explanation.

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 ('client's connected Facebook ad account and the conversions available'), clearly distinguishing it from sibling tools like list_clients and build_paused_campaign. The description explicitly names the sibling it pairs with and the scenario, leaving no ambiguity about what this tool does.

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 instructs when to call this tool ('Call this before build_paused_campaign on a leads or sales campaign') and explains why (those need a conversion to aim at). It also notes a prerequisite (manual Facebook connection) and the auth requirement (X-Mako-Key header), providing clear guidance on when and how to use 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?

With no annotations provided, the description carries the full burden; it discloses that the tool covers competitor report plans and mentions a specific monthly engagement ('May, the Meta ads agent'), which gives helpful context beyond a simple list operation.

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

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

The description is mostly concise with four sentences; the first two efficiently state function and usage, while the last adds context about a specific engagement, which, though slightly tangential, is still helpful for understanding the domain.

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 there are no parameters and no output schema, the description fully compensates by specifying what the list includes, why to use it, and how it relates to ordering, making it complete for a zero-parameter listing 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?

The tool has zero parameters, so the description doesn't need to explain parameters but it adds value by describing the output content (pricing, what's included, scope limits, etc.), making it clear what information the list returns.

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

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

The description clearly states the tool lists Mako Metrics plans with specific details (pricing, scope limits, delivery, guarantee, links), and distinguishes it from the only sibling 'create_order' by noting these plans are the products orderable through the server.

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

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

The description explicitly tells when to use this tool ('to recommend a plan before ordering') and implies not to use it for other actions, fitting well with the sibling 'create_order' which would be used after 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?

With no annotations provided, the description carries the full behavioral burden. It discloses that the report is not generated on the spot, that a human builds it, that it typically arrives within 24 hours, that it may spend quota or return a Stripe link depending on plan, and that an X-Mako-Key header is required. This is rich, non-obvious behavioral context.

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

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

The description is a tightly packed set of four sentences, each contributing a distinct piece of information: scope, plan behavior, async delivery, and follow-up/auth. It is front-loaded with the core purpose and contains 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 tool with no annotations and no output schema, the description covers the essential execution context: side effects, timing, plan variations, follow-up tools, and authentication. It could mention the immediate response shape or order identifier, but overall the operational picture is well supplied.

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 63%, and the description adds almost no parameter-level meaning. It repeats 'competitor' but doesn't explain the opaque goal enum values, market format, or title/notes semantics, leaving the uncovered parameter gaps unaddressed.

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

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

The description opens with a specific verb and resource: 'Order a competitor Meta ads report for one competitor.' This clearly identifies the tool's function and its single-competitor scope, differentiating it from the generic sibling create_order.

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

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

The description gives strong contextual usage guidance: plan-dependent behavior (spends allowance vs. Stripe checkout), the async nature, and the follow-up workflow 'Poll get_status, then list_deliverables.' It does not explicitly contrast this tool with create_order, but the conditions for use are otherwise 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?

With no annotations, the description carries the full behavioral burden and handles it well. It discloses that May creates a PAUSED campaign separately in the portal, 'never turns anything on,' 'never spends ad budget,' and usually completes in under a minute. This is far beyond a minimal mutation description.

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

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

The description is compact and front-loaded: purpose first, then duration, then safety, then prerequisites. Every sentence earns its place and no content is redundant.

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

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

The description thoroughly covers prerequisites, side effects, and safety, which is especially important because there is no output schema and no annotations. The only notable gap is that it does not describe the API response shape, though it does explain where deliverables land.

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 80%, and the schema already documents most parameters. The description adds context around prerequisites (confirmed brand profile, May plan, X-Mako-Key header) but does not meaningfully elaborate the parameters themselves, so the baseline of 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?

The description opens with a specific verb and resource: 'Start a May creative run for one client.' It enumerates concrete outputs (research, copy, eight ad concepts) and the delivery destination (portal), which clearly differentiates it from generic siblings like get_status or create_order.

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

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

The description gives explicit prerequisites: the client must have a confirmed brand profile, a May plan, and an X-Mako-Key header. It also sets runtime expectations. It does not name alternatives or give when-not-to-use conditions, so it falls just 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?

With no annotations, the description carries the full burden, and it does an excellent job. It discloses that only passed fields are changed, that calls are idempotent/safe to repeat, what confirming requires, and what authentication/plan is needed. This is exactly the behavioral context an agent needs beyond the 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?

Five sentences, each earning its place: purpose, mutation semantics, confirmation behavior, confirmation requirements, and prerequisites. The most important operational fact (partial update, safe to repeat) is front-loaded. No filler or repetition.

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

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

For a 27-parameter write tool with no output schema and no annotations, the description supplies the critical workflow context: how to update incrementally, when to confirm, what run_may needs, and required auth. It is slightly incomplete only because it does not describe what a successful response returns or what happens when confirm is false, and the "every field optional" claim conflicts with the 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?

The description adds useful cross-field semantics: only passed fields change, and confirming requires company_name, domain, flagship_product, offer_landing_page, target_customers, and both colors. However, it claims "Every field is optional," which conflicts with the schema's required client_account_id. It also does not compensate for the ~30% of parameters that lack schema descriptions. This is adequate but contains a misleading statement.

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?

Starts with a specific verb+resource combination: "Write or update one client's brand profile." This clearly distinguishes it from the read-only sibling get_brand_profile and from draft_brand_from_website, which creates the initial draft. The description also conveys the partial-update semantics without ambiguity.

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

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

Gives clear contextual guidance: it is safe to call repeatedly to correct a website draft, and confirm: true is what run_may needs. It also states prerequisites (May plan, X-Mako-Key header). However, it never explicitly names alternatives or says "use get_brand_profile to read" or "use draft_brand_from_website to create," so it stops short of a full when/when-not 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?

Even though no annotations are provided, the description clearly conveys that this is a read-only informational call ('Show') and discloses an important authentication requirement (X-Mako-Key header from makometrics.com/portal). It does not detail error behavior or output format, but the behavior is simple and well-scoped.

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, each earning its place: what is shown, when to call it, and what credential is required. The most important information is front-loaded and there is 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 zero-parameter, no-output-schema tool, the description covers everything needed to invoke it correctly: purpose, call ordering, and authentication. Nothing critical 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?

The tool has zero parameters, so the schema provides no meaningful burden and the description correctly adds none. The pointer to the required header is useful contextual information 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?

The description names a specific verb ('Show') and a specific resource (the Mako Metrics account tied to this key), and enumerates exactly what is revealed: plan, remaining competitor reports, and client workspaces. This clearly distinguishes it from all sibling tools like list_clients or create_order.

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

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

The description explicitly says to 'Call this first in any session that will use the customer tools,' providing clear situational guidance. It does not mention when not to use it or offer alternatives, but none are needed given its unique role.

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