Lodestone

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that: newest-first ordering, aggregation across all connected networks, and the shape of each returned chat. No pagination or result-count behavior is described, 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?

One sentence, front-loaded with the verb and resource, with the parenthetical supplying exactly the cross-network context an agent needs. Nothing is padded or 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?

With no output schema, the description usefully names the returned fields and ordering, which is what an agent needs to consume the result. It is slightly thin on pagination and on how the optional query/account filters interact with 'recent', but it is otherwise complete for a 3-parameter read tool.

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

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

Schema coverage is 100%, so limit, query and account are all fully documented in the schema itself. The description only gestures at the network concept via the parenthetical; it adds no format, default or example detail beyond the schema. Baseline 3 is correct where 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+resource ('List your recent Beeper conversations') and adds scope details: cross-network aggregation, newest-first ordering, and the three returned fields (ID, title, network). It doesn't explicitly differentiate from the sibling beeper_read_chats, which is the main reason it isn't 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 word 'recent' and the cross-network framing imply this is the browse/discovery entry point, and the query/account params hint at filtered variants, but the description never states when to use this instead of beeper_read_chats or beeper_search. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the ordering guarantee (newest last) and the content shape (who said what). It omits any mention of permissions, rate limits, or truncation behavior, keeping it out of the top tier.

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 with no filler; the purpose, return shape, and motivating context all arrive in one pass.

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, annotations covering the safety profile, and full schema coverage, the description supplies enough to call it correctly and interpret the result order. It could be marginally richer about what happens when the conversation is empty or the limit is hit, but nothing essential 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 (chatID origin, limit default/cap) are already fully documented in the schema. The description adds no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource (read recent messages in one Beeper conversation) plus the return shape (who said what, newest last). This clearly distinguishes it from sibling beeper_list_chats, beeper_search, and beeper_send_message without needing to open 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?

"so you have the context before replying" gives a clear triggering condition and implicitly routes to beeper_send_message as the follow-up action. It does not explicitly exclude alternatives or name the sibling, so it falls short of the 5 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds the 'across all your messages' scope but says nothing about result format, ordering, or the hard cap beyond what the annotations/schema provide, so it is adequate rather than rich.

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 tight sentence, front-loaded with the verb and resource, with no wasted words. The examples earn their place by illustrating query types.

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 search tool with full schema coverage and annotations covering the safety profile, the description gives an agent enough to invoke it correctly. It could mention result ordering or that results are per-message, but 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?

Schema description coverage is 100%, so every parameter is already documented. The description loosely signals the chatID and sender dimensions ('limited to certain chats or to messages from other people'), which reinforces but does not meaningfully extend the schema, making the baseline of 3 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?

Specific verb (search) plus resource (all your Beeper messages) and concrete query examples ('an address someone sent, a confirmation number') make the purpose immediately clear. It doesn't explicitly contrast with siblings like beeper_read_chats, 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 'optionally limited to certain chats or to messages from other people' hints at scoping usage, but there is no explicit when-to-use versus alternatives (e.g. beeper_read_chats for reading full threads) and no when-not guidance.

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

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

Beyond the annotations (readOnly=false, destructive=true, openWorld=true), the description discloses non-obvious behavior: the tool sends a real message to a real person, requires an explicit confirm gate, and automatically appends a Lodestone signature line on the Free plan. That footer behavior is critical context an agent could not infer from structured fields.

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 warning is front-loaded in brackets, followed by the core action, prerequisites, and one non-obvious system behavior. Every sentence contributes necessary information and there is no wasted phrasing.

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 destructive send tool with no output schema, the description covers the essential scope: what it does, who it affects, required preconditions, the confirm gate, and an automatic footer side effect. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by emphasizing the confirm:true safety gate and by warning the agent not to add the signature line into the text parameter, which directly affects how text should be filled.

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 opening bracket states the operation type and real-world consequence, then names the specific verb and resource: sending a text message to a Beeper conversation. The Beeper qualifier distinguishes it from sibling senders like telegram_send_message and email_send without needing to name them.

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

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

It gives explicit preconditions — read the thread first and confirm the exact text with the user — and reinforces the confirm gate. It does not explicitly name sibling alternatives or state a when-not-to-use case, so it falls short of the full 5 criteria.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description earns credit for adding genuinely new behavioral context: credentials are validated against the real provider before saving, failures return the specific reason, and credentials must never be echoed back. These details go well beyond the structured fields.

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 primary action and instructions, with no filler. The parenthetical slightly interrupts flow but every clause carries actionable content.

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

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

For a destructive, open-world write tool with no output schema, it covers validation, failure handling, field sourcing, and credential privacy. It omits what happens on success or whether an existing connection is overwritten, but remaining gaps are minor.

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 params are already documented (baseline 3). The description adds real meaning by specifying that field names must come from integration_guide, clarifying the nested 'fields' object's expected keys beyond the schema text.

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

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

States a specific verb+resource ('Connect one of the user's accounts') and clarifies the mechanism (values pasted in chat). It distinguishes itself from the external-website path and routes to the sibling integration_guide for field names, so an agent can identify it without inspecting the schema.

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

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

Explicitly states the supported usage ('values they pasted in this chat'), the exclusion ('do not send the user to a website instead'), and the prerequisite/discovery source ('Field names come from integration_guide'). This is the when/when-not/alternative guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by specifying what is destroyed (the saved credentials for a single account) and confining scope to "one of the user's accounts." It does not say whether the deletion is reversible or whether re-authentication is required.

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, zero waste, with the destructive action front-loaded and the usage condition immediately after. Nothing could be cut without losing meaning.

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 destructive tool with strong annotations and no output schema, the description covers action, target, and trigger condition adequately. Minor gap: it does not state that disconnecting requires reconnection via connect_integration, nor whether credential removal affects linked automations.

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

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

Schema coverage is 100% and the single parameter already carries an example ("email, telegram"). The description's "one of the user's accounts" loosely frames the parameter but adds no format or constraint detail beyond the schema, 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 and resource: "Remove the saved credentials for one of the user's accounts from Lodestone." An agent knows exactly what is being deleted and from where. It stops short of naming the inverse sibling (connect_integration), but the phrasing "disconnect or replace an account" ties it to that pair clearly enough.

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 only when the user asks to disconnect or replace an account" gives an explicit trigger condition and a restrictive "only" that discourages incidental use. It does not name the alternative tool (connect_integration) for the opposite operation, so routing is implied rather than spelled out.

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

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

Annotations already declare readOnly/openWorld/non-destructive safety, lowering the bar. The description adds genuinely novel context beyond them: that message_id is an IMAP uid scoped to the folder it was found in, not the Message-ID header. It still says nothing about ordering guarantees or pagination behavior.

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, zero filler, purpose front-loaded before the id-semantics clarification. Each 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?

There is no output schema, so the description partly compensates by explaining the returned message_id semantics. That is the key detail an agent needs to chain into email_read, though ordering and return shape remain unstated.

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%, including defaults and the max-50 cap, so the description adds no parameter detail the schema lacks. 'Default INBOX' merely restates the schema. Baseline 3 applies when the schema carries 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 and resource ('List the most recent emails in a folder') and names the default scope (INBOX). However, it never distinguishes itself from the sibling email_search, which an agent must choose between when retrieving mail.

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?

There is no explicit guidance on when to use this versus email_search or email_read. The only usage hint is the implied default folder. An agent has to infer the intended retrieval strategy on its own.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real context on top: the id is an IMAP uid 'scoped to the folder it was found in — not the email's Message-ID header,' which is a meaningful behavioral caveat. It omits auth requirements and rate limits.

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 tightly written sentences with no redundancy: the purpose is stated first and the parameter caveat second. 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?

For a read-only, two-parameter tool with no output schema, the description covers the return value ('full text of one email'), how to obtain the uid, and the folder scoping. Minor gaps like auth requirements remain, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, setting a baseline of 3, but the description goes further by explaining that message_id is an IMAP uid from the listed tools and is folder-scoped, not the Message-ID header. That is semantic value beyond the schema text.

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

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

States a specific verb and resource: 'Read the full text of one email ... by its uid.' The 'one email by uid' framing implicitly distinguishes it from the sibling search/list tools, but it never explicitly names them as the alternative.

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 points to email_search and email_list_recent as the sources of the uid, which implies when this tool is used. However, it gives no explicit when-to-use vs when-not guidance or conditions that would route an agent here over a sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: message_id is an IMAP uid, not the Message-ID header, and it is folder-scoped — a real misuse trap an agent would otherwise fall into.

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

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

Two sentences, front-loaded with what the tool does, followed by the identifier caveat. No filler. The second sentence concerns message_id, which is not a parameter of this tool, so it sits slightly outside the tool's immediate scope, but it is contractually useful.

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 does not describe the returned shape, but it implicitly signals that results carry a message_id usable downstream, and annotations cover the read-only/open-world profile. Adequate for an agent to call correctly, with the return format the only real gap.

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

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

Schema coverage is 100%, so the baseline would be 3. The description earns an extra point by clarifying what the 'query' parameter actually searches (From, Subject and body), which the schema only calls 'Text to search for'. It adds no detail for limit or folder, but those are fully specified in the schema.

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

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

States a specific verb (search) and resource (connected email account messages) and specifies the searched fields (From, Subject, body). It is distinguishable from email_read and email_list_recent by describing query-based matching, though it never explicitly contrasts itself with those siblings.

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

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

By noting that message_id comes 'from email_search or email_list_recent', it implies a workflow and hints these two are related entry points, but it never states when to prefer this tool over listing recent mail or reading a specific message. Usage is inferable rather than explicit.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely new context by disclosing the auto-appended "Sent via Lodestone" footer on the Free plan and instructing the agent not to duplicate it. It also constrains content to plain text. It does not mention whether sending is reversible, rate limits, or failure behavior.

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

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

Two sentences, front-loaded with the action and immediately followed by the one non-obvious behavior. Every clause carries information the agent would otherwise get wrong.

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 three-parameter send tool with full schema coverage and annotations, the description covers the main surprise (the footer) and the plain-text constraint. It leaves minor gaps around failure behavior and whether subject is optional, but nothing critical to invoking 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 100%, with per-parameter descriptions for to, body, and subject, so the schema carries the parameter burden. The description adds only the indirect implication that body must be plain text and that the footer should be excluded; it gives no format or constraint detail 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 states a specific verb and resource ("Send a plain-text email from your connected account") that clearly separates it from the read-only email siblings (email_list_recent, email_read, email_search). It does not explicitly name an alternative outbound-channel tool, but the send action is 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?

There is no guidance on when to use this versus other messaging tools (beeper_send_message, telegram_send_message) or on prerequisites such as having an account connected. The only conditional statement concerns footer appending, which is behavioral, not usage-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?

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine non-structured context beyond that: results are limited to properties the connected service account can read, which tells the agent why some properties may be missing. It does not mention pagination or result volume.

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 sentence, front-loaded with the verb and resource, with the access-scope caveat folded in rather than padded out. 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?

For a simple zero-parameter list tool with no output schema, the description covers purpose, scope and the returned identifier. It stops short of describing the full response shape (e.g. display names, account nesting), which is the only remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. It correctly signals the no-argument nature by not implying any filters.

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 (List) plus resource (GA4 properties) with a clarifying gloss of what a property is (sites/apps) and what identifying data comes back (property ids). It is distinguishable from the report-running siblings ga4_run_report and ga4_realtime_report, though the description never names them 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?

Usage is only implied: an agent can infer this is a discovery step to obtain property ids before calling ga4_run_report, but the description never states when to use it, when not to, or that it is a prerequisite for the report tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context – that data is realtime and bounded to a 30-minute window – which is the defining trait of this endpoint versus a standard report, though it omits things like data latency, sampling, or rate limits.

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

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

Single well-formed sentence with the resource and its scope front-loaded; no filler, no restatement of the name.

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-required-param, output-schema-less reporting tool, the description conveys what the call returns (active users broken down by a chosen dimension) and the recency window. It is reasonably complete, with only minor gaps around return format and the relationship to sibling GA4 tools.

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 each parameter (limit, filter, metrics, minutes, dimensions, property_id) is documented with defaults and examples, so the schema carries the load. The description's mention of country/page/traffic-source/device breakdowns loosely echoes the dimensions parameter but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (realtime active users in GA4) plus the exact scope: a 30-minute window broken down by country, page, traffic source or device. An agent can immediately distinguish this from the historical ga4_run_report sibling.

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 realtime framing implicitly tells the agent this is for 'right now' monitoring versus historical reporting, but it never names ga4_run_report or ga4_list_properties as alternatives, nor states when-not to use it. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the report targets the user's own site — nothing about GA4 quota/rate limits, sampling, or latency for large queries, which would be genuinely useful for a live external API.

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 sentence with a front-loaded verb, a colon-delimited operand list, and one worked example. No filler, and the highest-value information (what it does, what it accepts) comes first.

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 9 fully-documented optional parameters and annotations carrying the safety profile, the description needs to establish scope and it does. The absence of return-shape detail is acceptable since no output schema exists, though nothing explains what a result row looks like.

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's example filter ('sessionSource==instagram') and date phrasing ('over the last 28 days') are illustrative rather than additive syntax the schema lacks; the filter operator grammar lives in the schema, not 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?

States a specific verb+resource ('Run a Google Analytics 4 report') scoped to 'your own site', and enumerates the operands (dimensions, metrics, date range, filters). An agent can distinguish it from ga4_realtime_report and ga4_list_properties 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?

The embedded example ('sessions and conversions from Instagram by landing page over the last 28 days') gives concrete when-to-use context, and the schema note routes property discovery to ga4_list_properties. However, it never says when to prefer ga4_realtime_report or states any exclusion.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful output detail 'Returns the image inline' (valuable since there is no output schema), but says nothing about cost, latency, rate limits or prompt restrictions.

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 naming the model, its characteristics and its return behavior. No filler or repetition of the title.

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 'returns the image inline' note fills the main return-value gap, and the model characterization is a genuine differentiator. Missing only guidance on when to choose this over the sibling image models.

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 the prompt and the enum-constrained aspect_ratio are already documented in the schema. The description adds no parameter-level detail (no prompt length guidance, no default aspect ratio), so the baseline 3 applies.

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

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

States a specific verb (generate) and resource (image) plus the exact model variant (FLUX1.1 [pro]), which distinguishes it from sibling generators generate_image_nano_banana and generate_image_seedream. An agent can select it 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?

It lists suitable use cases (art, product shots, concept art) and speed/quality traits, which implies when this model fits, but it never names the sibling image generators or states when to prefer nano_banana or seedream instead. Usage is implied rather than guided.

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 declare readOnly=false, openWorld=true, destructive=false. The description adds the operationally critical traits annotations cannot express: it is SLOW (~30-40s), it returns the image inline, and it prescribes a pre-call UX step to avoid the wait looking like a hang.

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 capability and differentiators, then the return behavior, then the latency warning and the action to take. Every clause carries information; 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?

There is no output schema, but the description compensates by stating the image is returned inline and how long it takes. Combined with 100% schema coverage on both parameters, an agent has everything needed to call and wait correctly.

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

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

Schema description coverage is 100% with 2 parameters, and the enum of aspect ratios is fully documented in the schema. The description adds no format, syntax, or constraint detail beyond the schema, 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+resource ('Generate an image') and pins down the exact backend (Google's Nano Banana / Gemini 3 Pro Image), which distinguishes it from the sibling generators generate_image_flux and generate_image_seedream. It also names the domains where it wins (photorealism, legible text, complex compositional prompts), so an agent can choose without opening schemas.

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

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

Gives explicit selection criteria ('best for photorealism, legible text in the image, and following complex/compositional prompts') that route the agent among the image-generation siblings. It also adds a concrete invocation-time instruction: tell the user it is generating ~30 seconds BEFORE calling, so the wait is expected.

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 the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description usefully adds that the image is returned inline, which matters since there is no output schema, but it omits cost, latency, or how inline data is encoded.

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 tight sentence that front-loads the action and model, then adds the differentiator and the return behavior 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 no-output-schema generation tool the description covers what the agent most needs — the model, its strengths, and that the image comes back inline. Only minor gaps remain, such as resolution specifics or latency expectations.

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 schema description coverage at 100%, both parameters (prompt and aspect_ratio's enum) are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so 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 (Generate) and resource (an image), and names the underlying model (ByteDance Seedream 4.5), which cleanly distinguishes it from the sibling tools generate_image_flux and generate_image_nano_banana.

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 'high-resolution, strong at people, scenes and cinematic looks' gives an implicit selection criterion for choosing this model over its two image-generation siblings. It stops short of an explicit when-to-use statement or exclusions, 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 only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds critical traits annotations cannot convey: ~90s latency, client timeout risk, a returned link, and the billing consequence of retrying after an apparent failure.

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

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

Front-loaded with what it does and what it returns, then latency, then the alternative, then failure guidance. Dense and purposeful, though the all-caps emphasis and multi-clause failure instruction push it slightly past what a single read 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?

With no output schema, the description correctly states the return value (a link to the finished video), and it covers the operational hazards (latency, timeouts, double-billing on retry) an agent needs to call and handle this safely. Nothing material 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% with only 2 parameters, so the schema fully documents 'prompt' and the aspect_ratio enum. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Generate a short video') and names the exact model (Kling 2.5 Turbo Pro) plus the motion character it produces. This clearly differentiates it from the sibling generate_video_veo without needing to open either schema.

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

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

Explicitly routes the agent: use this for cinematic motion, but if the user needs speed, generate_video_veo is about 60s. It also prescribes pre-call behavior (warn the user about ~90s) and failure handling (do not silently retry), leaving nothing to inference.

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

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

Annotations say only readOnly=false, openWorld=true, destructive=false; the description supplies the traits that actually matter here – ~60s latency, per-duration credit pricing (60/90/120), audio included, and the retry-causes-rebilling hazard. That is exactly the beyond-annotations context an agent needs before a slow, paid, non-idempotent call.

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 what is produced, then cost, then latency, then the pre-call and failure-handling instructions. Every sentence carries actionable information – no filler and no repetition of schema fields.

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

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

No output schema, but the description states the return value (a video link). Combined with latency, pricing, audio and the retry hazard, an agent has everything needed to call this correctly and set user expectations.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by tying duration to explicit credit costs (4s=60, 6s=90, 8s=120), which the schema's duration enum does not convey. Aspect ratio is still left entirely to the schema, so it is not a full 5.

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 (Generate) and resource (video) plus the exact model (Google Veo 3.1 Fast) and the output ('link to the finished video'). An agent can distinguish it from generate_video_kling and the generate_image_* siblings by the named model and the fact it produces audio.

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 operative context: warn the user first, expect ~60s, do not silently retry on timeout because it may double-bill. It does not explicitly compare against the sibling generate_video_kling (cheaper/faster? different model quality?), so the alternative-selection guidance is incomplete.

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

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

The annotations already declare write, destructive, and open-world behavior, and the description's '[WRITE — public]' tag and confirm requirement largely restate that. It adds little beyond the annotations and schema — no indication of what closing does to the issue state, whether the comment can be edited/deleted, or auth requirements.

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 sentence with the write/public tag front-loaded, the primary action stated immediately, and the confirm requirement called out last. Nothing is wasted.

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

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

No output schema exists, but full schema coverage plus declarative annotations cover most of what an agent needs. The only remaining gap is the effect of the close flag on the issue's state and failure behavior, which the description does not surface.

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 every parameter (body, repo, close, number, confirm) is already documented in the schema. The description mentions the confirm gate and the optional close behavior, but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

The description gives a specific verb and resource ('Post a comment on a GitHub issue or pull request') plus a secondary action ('optionally close the issue'), which cleanly separates it from github_create_issue and github_get_issue. It does not explicitly name a sibling it overlaps with, so it falls just short of 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?

It states a concrete precondition for use ('Requires confirm:true'), which is more than most write tools offer. It gives no exclusion or when-not guidance (e.g. when to prefer github_create_issue), so it is clear context without alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for the extra context: auto-creation of the branch from the default branch, the hard refusal of the default branch, and the confirm:true safety gate. It does not spell out that file contents are overwritten wholesale (that only appears in the schema's 'COMPLETE new file content' note), which is the main remaining destructive-behavior detail.

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, front-loaded with the [WRITE] marker and the core action, then the branch-creation behavior, then the constraint and safety gate. 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 destructive, open-world write tool, the description covers the critical call-correctness facts: branch auto-creation, default-branch refusal, and the confirm gate. Missing only return-value expectations (e.g. resulting commit SHA/branch URL), which is a modest gap given no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents repo, branch, base, message, files and confirm including the confirm safety gate. The description only reinforces the confirm requirement and the branch-creation semantics from base, adding little beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ('Commit changes to one or more files as a single commit on a branch') with the scope of atomicity made explicit. It is clearly distinguishable from github_create_pr, github_get_file and github_comment among the siblings.

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

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

Gives an explicit routing rule: it refuses the default branch, and the correct alternative workflow is 'commit to a new branch, then open a pull request'. That names both the exclusion and the follow-up tool path. It stops short of explicitly naming github_create_pr as the next call, hence 4 rather than 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 declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered externally. The description adds the '[WRITE]' marker and the confirm gate, which reinforces intent, but says nothing about what the call returns (issue number/URL) or that the issue is visible to others immediately. With annotations carrying the main burden, this is adequate but thin.

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

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

Two short sentences, zero filler, with the write marker and confirm requirement front-loaded. Nothing here is wasted or 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 simple create operation with full schema coverage and clear annotations, the description covers enough to invoke correctly. However, with no output schema, an agent gets no hint of what comes back (issue URL or number), which is commonly needed to chain into github_comment or a follow-up read.

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%, with each of the five parameters (including confirm and the owner/name repo format) documented inline. The description adds no syntax, format, or constraint detail beyond the schema, 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 and resource ('Open a new issue in a GitHub repository') that an agent can immediately distinguish from github_get_issue, github_comment, and github_create_pr. It does not explicitly name a sibling or contrast with one, but the name-plus-description pairing is 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?

Usage is only implied by the tool name and the '[WRITE]' tag; there is no statement of when to use this versus github_comment or github_create_pr, and no prerequisite context (e.g., repo must exist, labels must pre-exist). The 'Requires confirm:true' note is the only explicit usage guidance, and that is already restated in the schema.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the '[WRITE]' tag adds nothing new. The confirm gate is useful behavioral context, but it is already spelled out in the schema parameter description, and the description says nothing about required GitHub permissions, failure modes when a PR already exists, or what is returned.

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

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

Two short sentences with the write marker, the action, and the safety precondition front-loaded. Nothing is redundant or padded.

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 open-world write tool with no output schema, the agent still does not know what the call returns (PR number/URL) or how duplicate-PR situations behave. The fully documented schema and write annotations keep it at an adequate level rather than a failing one.

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 every parameter (repo, head, base, title, body, draft, confirm) is documented in the schema itself. The description only echoes head/base semantics, adding no syntax or format detail beyond what is already structured.

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 concrete verb and resource ('Open a pull request') plus the direction of the operation (branch into default branch or another base), which separates it cleanly from github_merge_pr and github_create_issue. It does not name any sibling explicitly, so it stops short of the top score.

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?

'Requires confirm:true' tells the agent the precondition for acting, and the head/base phrasing implies when the tool applies. However, there is no explicit guidance on when to prefer it over github_merge_pr or github_create_branch_commit, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is known. The description adds the non-obvious trait that a directory path returns a listing rather than an error. It says nothing about large-file truncation, binary content, or encoding, which matter for a raw file read.

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 zero filler; the core action is front-loaded and the edge case (directory path) follows immediately after.

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

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

With no output schema, the description carries the burden of explaining what comes back, yet it never describes the return shape (raw content vs base64 blob, metadata fields) or handling of large/binary files. Adequate for selecting the tool, thin for predicting the response.

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

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

Schema coverage is 100% and all three parameters carry descriptions, so the baseline is 3. The description's phrase "any branch, tag or commit" simply restates the ref parameter's own text and adds no extra syntax or defaulting detail.

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 ("Read one file from a GitHub repository") and adds the scope of refs supported. The second sentence clarifies directory behavior, which separates it from a plain file reader, though it never names the sibling it displaces (e.g. github_list_tree).

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?

Usage is implied by "Read one file" and "Passing a directory lists it," but there is no explicit routing guidance such as "use github_list_tree to browse a repo first" or when to prefer github_search for locating a path. An agent must infer the boundary with siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that the result includes the full description and comments, but says nothing about how comments are paginated/truncated or what happens with the default limit.

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

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

One tight sentence that front-loads the verb and resource with zero 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?

No output schema exists, so the description must convey the return payload; it does so by naming the issue body and comments. Slightly short of complete because it doesn't address comment truncation or the default limit behavior an agent might need.

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 repo, number, and comment_limit are already documented with formats and defaults. The description adds no further meaning about parameter behavior beyond the schema.

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

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

States a specific verb (Get) and resource (one GitHub issue) plus the payload returned (full description and comments). The singular 'one issue' implicitly distinguishes it from github_list_issues and github_search, though no sibling is named 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?

Usage is only implied: an agent can infer this is the tool for fetching a single issue's detail, but there is no explicit statement of when to prefer it over github_list_issues or github_search, and no prerequisites mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful scope detail by listing what the response aggregates (mergeability, per-file diff stats, three flavors of comment threads), but says nothing about pagination of comments or response size for large PRs.

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 with the verb and resource first, followed by the returned fields. No filler, no repetition of the title.

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 usefully compensates by enumerating the returned data. It is a simple two-parameter read tool with full schema coverage, so the description is nearly complete; only the aggregation size/pagination of comments is left unaddressed.

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

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

Schema coverage is 100% and both parameters (repo, number) are fully documented in the schema, including the owner/name and URL formats, so the description carries no additional parameter burden. It adds no syntax or format detail beyond the schema, making the baseline of 3 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?

Specific verb ('Get') plus resource ('one GitHub pull request') with an enumeration of the sub-resources returned: description, mergeability, diff stats per file, reviews, comments, review comments. The singular 'one' implicitly separates it from github_list_prs, but no sibling is named explicitly, which keeps it 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?

Usage is only implied: fetching a single PR by repo/number versus listing them. There is no explicit 'use this when' statement, no mention of github_list_prs as the alternative for browsing, and no guidance on when the comment/review payload is overkill.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description still adds genuine context the annotations do not: the result ordering and the important gotcha that PRs are filtered out of issue listings. It stops short of describing pagination or return shape, which keeps it below 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?

Two short sentences with zero filler. The primary behavior and its sorting are front-loaded, and the sibling routing is placed in a compact trailing clause.

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

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

For a read-only list tool with 100% schema coverage and annotations covering safety, the description supplies everything needed to select and invoke it, including the PR exclusion that would otherwise cause surprise. Only return-field expectations and pagination behavior are unaddressed, which is minor given there is no output schema.

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

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

Schema coverage is 100%, so repo format, limit bounds (default 20, max 100), state enum with its default, and comma-separated labels are all fully documented in the schema. The description only echoes that state/label filtering exists, adding no format or syntax detail beyond structured fields. 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?

Specific verb (List) plus resource (issues) plus scope (in a GitHub repository) plus ordering (most recently updated first). It explicitly excludes pull requests and names the sibling to use instead, so an agent can separate it from github_list_prs and github_get_issue without opening either schema.

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

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

States the filtering conditions it supports (state, label) and explicitly names the alternative for the case it does not cover: "Pull requests are left out; use github_list_prs for those." Nothing about when to pick this tool over its sibling is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful behavioral context about ordering ('most recently updated first'), but it does not mention authentication, rate limits, or pagination behavior beyond what the schema implies.

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 efficient sentence with the core operation front-loaded. The parenthetical ordering note is concise and useful. No wasted words.

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

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

For a simple read-only list tool with full schema coverage and annotations covering safety, the description is largely complete. It could optionally clarify return shape or pagination, but no output schema exists and the core operation is clear.

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

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

Schema description coverage is 100%, and all three parameters (repo, limit, state) are documented in the schema. The description adds no parameter-level meaning beyond the schema, so the baseline score 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 states a specific verb and resource: 'List pull requests in a GitHub repository.' It also adds ordering context ('most recently updated first'). It does not explicitly distinguish itself from nearby siblings such as github_list_issues or github_search, but the resource noun makes the intended operation clear.

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 no guidance on when to use this tool versus alternatives like github_search or github_get_pr. Usage is only implied by the verb 'List.' There are no exclusions or selection criteria provided.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description only adds the path/repo scoping distinction; it says nothing about result truncation or what happens when the limit is hit, which is the main behavioral risk for a repo-wide listing.

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 with no filler; the scoping and the downstream purpose both land immediately.

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 4 fully documented params and no output schema, the definition gives enough to call the tool correctly for a read-only listing. What is missing is any hint about the shape or size of the returned tree entries, which would help an agent plan follow-up reads.

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 repo/path/ref/limit are all documented in the schema and the baseline of 3 applies. The description implies the path parameter's meaning ("under one path") but adds no format or default-branch detail beyond the schema.

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

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

States a specific verb and resource ("List the files and folders in a GitHub repository") and scopes it ("whole repo or under one path"), which cleanly separates it from github_get_file (single file read) and github_search (query-based lookup).

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?

"so you can find what to read" tells the agent this is the discovery step that precedes github_get_file, giving clear usage context. It stops short of naming that sibling explicitly or stating any exclusion, so it does not reach 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 declare destructive=true, readOnly=false and openWorld=true, so the safety profile is covered. The description adds useful context beyond annotations: it changes the target branch, requires an explicit user request, and enforces a confirm:true gate.

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

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

It is a short, front-loaded description. The write warning, action, usage constraint, and safety gate all appear immediately with no wasted words.

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

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

For a destructive GitHub mutation with full parameter documentation and rich annotations, the description gives everything needed to call it correctly: what it does, when to use it, and the confirm requirement.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description reinforces the confirm gate and method choices but adds little semantically 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 and resource (merge a GitHub pull request) and specifies the supported merge strategies, making it clearly distinct from read-only siblings such as github_get_pr and github_list_prs.

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 condition for use — only when the user has explicitly asked to merge — and states the confirm gate. It does not name a specific alternative sibling, but no alternative applies for a merge operation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety and external reach are covered. The description adds the search-syntax flavor and the global-vs-repo scope, but says nothing about GitHub's strict search rate limits, result ordering, or pagination behavior.

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 constraint front-loaded and a concrete syntax example appended. Nothing is redundant and the reader knows what the tool does after the first clause.

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

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

With four fully documented parameters, a required query, and no output schema, the definition is nearly self-sufficient. The only real gap is that result shape and rate-limit behavior are unaddressed, which a search tool against GitHub's throttled API arguably warrants.

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%, including enum values and defaults for type and limit, so the baseline is 3. The description's example query ("label:bug is:open login") reinforces the qualifier syntax already documented in the query parameter, adding illustrative value rather than new 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?

The description gives a specific verb ("Search") and resource ("GitHub issues, pull requests or code") plus the scope distinction of global vs. single-repo. This separates it from list-style siblings such as github_list_issues and github_list_prs, though it never names an alternative 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?

Usage is implied by "Search GitHub for..." and the syntax example, giving the agent a clear sense of when the tool applies. However, there is no explicit when-not guidance and no named alternative (e.g., github_list_issues for unqueried listing), so routing must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating the returned fields in the absence of an output schema, but says nothing about error behavior, missing connection, or permission scoping.

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

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

One front-loaded sentence with no wasted clauses, and the returned-field list is packed efficiently. It's tight and readable, though it is so terse that it omits routing information a sibling-heavy toolset 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 simple single-param read with full schema coverage and safe annotations, the definition covers purpose and returned fields adequately. The only real gap is disambiguation from google_ads_list_accounts and google_ads_whoami in a crowded Google Ads sibling set.

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

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

Schema coverage is 100% and the single parameter documents digits/dashes tolerance and the 'defaults to your connected account' behavior. The description adds nothing about customer_id, so it rests at the baseline rather than earning above it.

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

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

States a specific verb ('Get details') and resource ('your Google Ads account') and enumerates exactly what comes back (name, currency, timezone, manager/test flag). That said, it never distinguishes itself from close siblings such as google_ads_list_accounts or google_ads_whoami, so an agent can't tell from the text which of those to pick.

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?

Usage is only implied: 'your Google Ads account' suggests the single connected account, and the field list implies 'use me when you need account metadata'. There is no explicit when-to-use, no exclusion of list_accounts/whoami, and no statement about prerequisites such as needing a completed Google Ads connection.

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

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

The bracketed '[WRITE — changes your live account]' and 'Requires confirm:true' add real value beyond the annotations by flagging the safety gate and irreversibility of a live mutation. However it says nothing about duplicate handling, partial-batch failure, or error behavior for a live-account write, so it stops short of rich disclosure.

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

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

Two tight sentences: the risk tag and confirm gate are front-loaded, followed by the action. No sentence is wasted.

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

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

For a 6-parameter write tool with no output schema, the description plus fully documented schema cover what an agent needs to call it correctly. Only failure/partial-success behavior for the batch mutation 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%, including enum values for match_type and the default for negative, so the schema carries the parameter burden. The description adds no format or interaction semantics beyond what is already documented, making baseline 3 correct.

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 (Add), resource (keywords) and target container (an ad group) with batch scope, plus the negative-keyword variant. An agent can distinguish this from sibling read/research tools like google_ads_keyword_ideas 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?

It states the mandatory precondition (confirm:true) and implies batch semantics, but never names alternatives or when-not-to-use — e.g. whether to prefer google_ads_update_ad_group or how this differs from keyword research. Usage is inferable but not routed.

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 annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: it is a live-account write, the result is created in PAUSED state, and a confirm gate must be passed. It does not contradict the annotations; the write framing is consistent with readOnlyHint=false.

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

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

One compact line, front-loaded with the most decision-relevant signal (WRITE to live account) and then the creation semantics. 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?

For a mutation tool with annotations and full schema coverage, the description covers the safety gate, default status, and bid unit. The one gap is return behavior — with no output schema, the agent isn't told whether an ad group id or resource is returned.

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

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

Schema coverage is 100%, so all six parameters are already documented including MICROS units and the confirm gate. The description mostly restates the schema's key facts (MICROS bid, PAUSED default, confirm:true) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an ad group under a campaign') and scopes it to the Google Ads domain, making it clearly distinct from google_ads_create_campaign and google_ads_update_ad_group. An agent can route to it 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?

It gives operational prerequisites (requires confirm:true, created PAUSED) but never states when to use this versus update_ad_group or how it relates to campaign creation. Usage is implied rather than directed.

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

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

Goes well beyond the annotations: it flags this as a live-account WRITE, discloses the resulting state (PAUSED, no spend), and states the confirm:true safety gate. Annotations only say readOnly=false / destructive=false / openWorld=true, so the description carries the meaningful behavioral context itself.

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

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

Four tight clauses, front-loaded with the highest-risk information ('WRITE — changes your live account') followed by what is created, its initial state, units, and the gate. 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?

No output schema exists, and the description never says what comes back (e.g., a campaign id needed to create ad groups or ads under it), which is the main chaining gap. Everything else an agent needs to invoke it correctly — mutation risk, default paused state, unit convention, confirm gate — 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 every parameter is already documented in the schema. The description repeats the MICROS unit for budget and the confirm gate but adds nothing about status, name, or customer_id defaults, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a new SEARCH campaign') plus the bundled side artifact (its daily budget), which is the key differentiator from google_ads_update_campaign or google_ads_update_budget. The campaign type (SEARCH) is named explicitly, so an agent can tell exactly what kind of object this produces.

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 usage context: the campaign is created PAUSED and won't spend until activated, so an agent knows this is a safe first step followed by google_ads_set_status. It does not explicitly name alternatives (update_campaign, create_ad_group, add_keywords) or state prerequisites like having a customer_id/account connected, so it falls short of 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?

Beyond the annotations, it discloses that this mutates a live account, that the result is created PAUSED by default, and that a confirm gate applies — real safety context. Slight tension: it says 'Created PAUSED' while the status param also accepts ENABLED, so the true default behavior is a bit ambiguous.

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

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

One tightly packed sentence-plus-bracket, with the safety warning front-loaded before the operational detail; nothing is wasted.

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

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

Covers the essentials for a 9-parameter mutation tool with full schema coverage and no output schema: write risk, confirm gate, default status, and format. Only gap is what the call returns (ad id?), which an agent might want but can discover.

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 every parameter is already documented, including the pipe-separated format and length limits. The description repeats those constraints ('>=3 headlines <=30 chars', '>=2 descriptions <=90 chars') but adds no semantics beyond the schema — baseline 3.

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 ('Create a responsive search ad in an ad group') and names the concrete constraints, making it clearly distinct from google_ads_create_ad_group, google_ads_get_ad, and google_ads_list_ads.

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 '[WRITE — changes your live account]' prefix and 'Requires confirm:true' establish when this applies versus the read-only siblings (get_ad, list_ads). It does not, however, say prerequisites such as the ad group needing to exist or point to an alternative tool for other ad types.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally; the description's useful addition is the parenthetical listing which fields come back. It does not mention behavior on a missing/invalid ad id, cross-account resolution, or rate limits. With annotations carrying the safety load, a 3 is appropriate.

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 sentence, front-loaded with the verb and resource, with the field list appended as a compact clause. Nothing is redundant or padded.

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 read-only getter with full annotation coverage and full schema coverage, this is close to sufficient, and the field list partly compensates for the absence of an output schema. It stops short of describing not-found behavior or the account-resolution fallback beyond what the schema notes.

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 ad_id and the optional customer_id (with its default-to-connected-account note) are already documented in the schema. The description adds only the confirmation that the lookup is keyed on id, which is the baseline expectation 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 and resource ('Get one Google Ads ad by id') and enumerates the fields returned, so it is clearly a single-record fetch rather than a list. It does not explicitly name google_ads_list_ads or google_ads_query as the alternative, so sibling differentiation is only implied by 'one ... by id'.

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 'by id' framing implies you need a known ad id, which implicitly contrasts against list/search tools, but no when-to-use or when-not-to-use guidance is stated. Nothing tells the agent what to do if it only has a campaign or ad group name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description contributes the returned-field set (status, type, max CPC, parent campaign), but says nothing about error behavior for unknown ids or account scoping.

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 with no filler; the resource, key, and returned fields all appear in one clause.

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

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

There is no output schema, so listing the returned fields is genuinely useful and largely fills that gap. An agent has enough to call it correctly; only error/scoping behavior is left implicit.

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

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

Schema description coverage is 100% and both parameters are documented there, including the optional customer_id default. The description only echoes 'by id' and adds no format, example, or fallback meaning beyond the schema.

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

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

States a specific verb and resource ('Get one Google Ads ad group') plus the lookup key ('by id'), which implicitly distinguishes it from google_ads_list_ad_groups. It also names the returned fields, but never explicitly contrasts itself with list_ad_groups or google_ads_query.

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?

Usage is only implied: fetch a single ad group when you already have its id. There is no guidance on when to prefer google_ads_list_ad_groups or google_ads_query instead, and no prerequisites (e.g., requiring a customer_id or connected account) are mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (status, channel type, budget, schedule), but says nothing about behavior when the campaign id is not found or when customer_id resolves to a different account.

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 with the key and the returned fields in parentheses; no filler, no repetition of annotation-derived facts.

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, naming the returned fields is a genuine contribution and covers what an agent needs to know before calling. Only the not-found / cross-account behavior is left unstated, which is a minor gap for a simple read.

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

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

Schema coverage is 100% and both parameters are documented there, including the customer_id default behavior. The description adds only the 'by id' framing and does not mention customer_id at all, 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 ('Get one Google Ads campaign') plus the lookup key ('by id'), which implicitly separates it from google_ads_list_campaigns and google_ads_update_campaign. No sibling is named explicitly, so it falls just short of 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 'one ... by id' implies this is the single-record fetch versus the list tool, but the description never says when to prefer this over google_ads_list_campaigns or google_ads_query. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's burden is lighter. It adds the useful fact that results are aggregated by level/date range, but says nothing about row caps beyond 'limit', pagination behavior, or what happens when the account has no data.

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 dense sentence that front-loads the returned metrics before the breakdown dimensions and window. No filler, though it is terse enough that an extra clause on aggregation/read-only reporting could have earned 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 read-only reporting tool with no output schema, the description correctly enumerates the returned metrics and the available granularity, which is the key missing piece otherwise. It omits any indication of response shape (row objects, totals) but is adequate to call the tool correctly.

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

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

Schema description coverage is 100% with defaults and a full enum for date_range documented inline, so the schema carries the semantics. The description adds no extra meaning for level, limit, date_range, or customer_id beyond what is already declared.

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 ('Get') plus the exact resource and metric set (impressions, clicks, cost, CTR, avg CPC, conversions) and the three supported breakdown levels. That makes the purpose unambiguous, but it never names or contrasts with siblings like google_ads_query or google_ads_get_campaign, so it falls 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?

Usage is only implied by the metric/breakdown framing; there is no explicit 'use this when you want aggregated performance reporting rather than raw rows or a single-entity lookup'. No when-not conditions or prerequisites (e.g. account connected) are stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond that: data comes from live Keyword Planner (not cached), and it enumerates the metrics returned. It omits any note on quota/rate behavior of the Ads API, which keeps it below 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?

A single tight sentence with the resource, source, and returned metrics front-loaded; no filler or repetition of structured fields.

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 zero required parameters and no output schema, the description usefully previews the return fields (searches, competition, CPC), which is what an agent most needs. It does not state that at least one of keywords/url must be supplied, a minor gap for a 6-param tool.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including defaults. The description only reinforces the keywords/url duality ('and/or'), adding nothing about format or the mutual-optionality constraint beyond what the schema states.

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

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

States a specific verb and resource ('Research keywords via Google Keyword Planner') and names the concrete data returned: average monthly searches, competition, top-of-page CPC. It is clearly distinct from write-side siblings like google_ads_add_keywords, though it never names an alternative 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?

Usage is only implied: the description says it works 'for seed keywords and/or a page URL,' which signals the two input modes but not when to pick this over google_ads_query or google_ads_insights. No exclusions or preconditions are stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results are scoped to the connected sign-in, but it does not mention pagination, return volume, or exact output format.

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 communicates the action, scope, and immediate use of the result. There is no redundant or filler text.

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 no-parameter read-only listing tool, the description provides enough context to call it correctly. It identifies what is returned (Customer IDs) and their access scope, though it could note whether the list is paginated or arbitrarily long.

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 zero parameters, so no parameter guidance is required. The description stays appropriate for a parameterless listing operation and introduces no misleading parameter implications.

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: it lists Google Ads Customer IDs accessible to the connected sign-in. It does not explicitly differentiate itself from related siblings like google_ads_account_info or google_ads_whoami, but the resource and access scope are clear.

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 explains the practical purpose of the result: use one returned Customer ID in Lodestone. It does not name alternative tools or state when not to use it, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no mention of pagination behavior, default result ordering, or what fields each ad group includes, which would be the value-add an agent needs for a 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?

A single well-formed sentence with the primary purpose front-loaded and the optional scope qualifier immediately after. No filler, no repetition of the title or annotations.

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

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

For a simple, fully optional-parameter read tool with complete schema descriptions and clear read-only annotations, the description covers the essentials. The only gap is the absence of any note on return shape or pagination, which matters slightly given there is no output schema.

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

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

Schema description coverage is 100%, so all three parameters (limit, campaign_id, customer_id) are already documented, including defaults and formats. The description's "just those in one campaign" only restates the campaign_id filter already in the schema, adding no new semantic detail. 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 ("List ad groups") plus the Google Ads account context, which distinguishes it from get_ad_group, create_ad_group, and update_ad_group. It does not explicitly name those siblings or explain when to prefer google_ads_query instead, so it falls short of full sibling differentiation.

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 "or just those in one campaign" implies the optional-narrowing scenario, but usage is only inferred. There is no explicit guidance on when to use this versus google_ads_query or list_campaigns, and no stated prerequisites about needing a connected account beyond what the customer_id schema note says.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds only the scoping behavior; it says nothing about pagination, result caps beyond the schema's 'limit', or ordering, so the added behavioral context is thin.

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 with zero filler; the account-wide default and the ad-group narrowing are stated compactly and in the right order.

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

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

For a zero-required-parameter, read-only list tool with full schema coverage and clear annotations, this is close to complete. The only mild gap is the absence of any hint about paging through large result sets, though the limit parameter partly covers it.

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

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

Schema description coverage is 100%, with limit (default 25), ad_group_id, and customer_id all documented in-schema. The description restates the ad_group_id filter but adds no syntax, default, or fallback detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('List ads') plus scope ('in your Google Ads account, or just those in one ad group'). This distinguishes it implicitly from google_ads_get_ad (single ad) and google_ads_list_ad_groups/list_campaigns, though 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?

The 'or just those in one ad group' clause implies when to pass ad_group_id, but there is no explicit when-to-use/when-not guidance or named alternative (e.g. google_ads_query for filtering by campaign or status). Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming returned fields—status, channel type, and daily budget—but it does not describe pagination behavior, limits, or authentication requirements.

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 front-loaded sentence with no wasted words. It concisely states the core action and the key returned fields.

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 read-only list tool with a fully described schema and useful annotations, the description is largely complete and even names returned fields despite no output schema. Its main omission is sibling differentiation, which would help agents choose between this and google_ads_query or google_ads_get_campaign.

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

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

Schema description coverage is 100%, so the schema already documents limit, status, customer_id, defaults, and enum values. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 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 states a specific verb and resource—'List campaigns'—and identifies the Google Ads account scope plus returned fields. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like google_ads_get_campaign or google_ads_query.

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

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

The description provides no explicit when-to-use guidance, prerequisites, or alternatives. It only implies usage through its purpose; it never says when this tool should be chosen over google_ads_get_campaign, google_ads_query, or other listing tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond annotations by stating that results are returned as raw JSON rows, which matters because no output schema exists.

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

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

The description is two tight sentences with no wasted wording. The primary action and fallback scope are front-loaded, followed by the return format.

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 flexible query tool with fully documented parameters and annotations covering safety, the description is largely complete. It states the return format but, without an output schema, does not describe the shape of returned rows in detail; this is a minor gap rather than a blocking omission.

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

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

The input schema has 100% description coverage for all three parameters, including query syntax and limit default. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate when the schema does the work.

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 operation: running a read-only GAQL SELECT query. It also clearly positions the tool as a fallback for reads not covered by the other Google Ads read tools, so an agent can distinguish it from siblings like google_ads_insights or google_ads_list_campaigns.

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 'anything the other read tools don't cover' gives clear guidance to use this only when a dedicated read tool is insufficient. It does not explicitly name the preferred alternatives or state when not to use it, but the fallback intent is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is partly covered. The description still adds value with the [WRITE — changes your live account] banner, the concrete consequence 'Pausing stops spend', and the confirm gate — real effects rather than restated hints. It does not mention reversibility, propagation delay, or rate limits.

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, with the most important fact (this mutates a live account) front-loaded in a bracketed banner. Nothing is redundant or padded.

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 destructive mutation with no output schema, the description correctly conveys effect, target level, and the confirmation requirement, and the annotations plus rich schema cover the rest. It is slightly thin on what a successful call returns or whether the change is instantly reflected.

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 every parameter (level, status, confirm, object_id, customer_id) is documented in the schema, so the baseline is 3. The description only echoes the status and confirm semantics already present in the schema, adding no new parameter detail.

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 pair (pause/resume) and the exact resource scope (a campaign or ad group by id), which is clearly narrower than google_ads_update_campaign/ad_group. It does not explicitly say why to prefer this over passing a status field to the update tools, so sibling differentiation is implied rather than stated.

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 use case (stop or restart spend) and flags that confirm:true is required, but it gives no when-not guidance and names no alternative tool. An agent must infer that bulk/create/update operations belong to the sibling google_ads_* tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds a useful live-account warning and highlights the confirm:true safety gate. It does not explain whether unspecified fields are preserved or what the response contains, but the added safety context is meaningful.

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

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

The description is compact and front-loaded with the most important warning — that this is a write operation affecting the live account — followed by the required confirm gate and the updatable fields. 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?

Given full schema coverage and destructive annotations, the description supplies the essential safety gate and field scope. It is complete enough to invoke correctly; only minor edge-case details like preservation of unmentioned fields are absent, and no output schema exists so return-value explanation is not required.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including customer_id and ad_group_id. The description reinforces the updatable fields and MICROS unit but adds little meaning beyond what the schema provides; 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?

The description states a specific verb and resource — update a Google Ads ad group — and names the updatable fields (name, status, max CPC bid). It is clear what the tool does, but it does not differentiate itself from siblings like google_ads_set_status or google_ads_update_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?

The description makes clear this is for updating an existing ad group's name, status, or bid and that confirm:true is required. However, it provides no explicit when-not guidance or routing to alternatives such as google_ads_set_status, google_ads_update_campaign, or google_ads_get_ad_group.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds real value beyond that: '[WRITE — changes your live account]' and 'Affects every campaign sharing that budget' disclose the blast radius, which is not in the annotations, and it states the confirm:true safety gate. It still omits reversibility and expected response, keeping it short of a 5.

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

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

Three short clauses, front-loaded with the write/live-account warning, then the scope, then the gate. Zero wasted words.

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

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

For a destructive mutation with no output schema, the description covers the critical agent-facing facts: write nature, budget-sharing impact, and the confirm requirement. It is nearly complete, though it does not say what is returned or how a change could be reverted.

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

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

Schema coverage is 100%, so all four parameters are already documented including the MICROS example and the confirm gate. The description only echoes the MICROS unit and confirm requirement, adding no meaning beyond the schema – the baseline 3 applies.

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

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

States a specific verb and resource ('Change a campaign budget's daily amount') and scopes it to budgets rather than campaigns. It does not explicitly name google_ads_update_campaign as the sibling that handles other campaign settings, so the differentiation is implicit rather than stated.

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 usage (a live write with a confirm gate) and the schema points to google_ads_get_campaign for finding the budget id. But there is no explicit when-to-use-this-vs-update_campaign guidance and no stated exclusions or prerequisites beyond the confirm flag.

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

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

The '[WRITE — changes your live account]' prefix adds practical emphasis beyond the annotations, and calling out confirm:true in prose surfaces the safety gate at a glance. Annotations already declare destructiveHint/openWorldHint, so the description's marginal value is modest but real; it does not, however, say what happens to other campaign settings or what the response contains.

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 plus a bracketed tag, front-loaded with the most important fact (this writes to a live account). Nothing is wasted and the routing hint is placed immediately after the scope statement.

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 narrow mutation tool with full annotation coverage and a complete schema, the description supplies the essential safety framing and out-of-scope redirection. The only meaningful gap is the unaddressed overlap with google_ads_set_status.

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 every parameter including the confirm safety gate and the status enum is already documented. The description merely echoes 'name and/or status' and 'confirm:true' without adding format or behavioral detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource (update a Google Ads campaign) and limits scope to name and/or status, which is precise. It differentiates from google_ads_update_budget but never addresses the sibling google_ads_set_status, which appears to overlap substantially with the status change this tool claims — leaving a real ambiguity an agent must resolve on its own.

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 routes an adjacent action to another tool ('Budget changes go through google_ads_update_budget') and states the confirm:true requirement. What's missing is guidance on when to use this versus google_ads_set_status for pause/resume, so the alternative-selection story is only half complete.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by telling the agent what the call actually verifies and what it returns conceptually (accessible account count), which the annotations do not.

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

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

One sentence, front-loaded with the verification purpose and followed by the observable outcome. No filler, no restating the tool name.

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, read-only diagnostic with no output schema, the description covers enough: what it tests and roughly what it reports. A hint about failure behavior (e.g. what a failed auth looks like) would make it complete, but the essentials are 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?

The tool takes zero parameters, so the baseline of 4 applies. Nothing about argument semantics needs explaining, and the description correctly does not invent any.

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

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

States a specific action (verify the connected Google Ads account works) and a specific output (how many accounts the sign-in can access). This is clearly distinct from data-reading siblings like google_ads_list_accounts or google_ads_query, though it never names those siblings explicitly to sharpen 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?

The phrasing implies a preflight/health-check use case, but there is no explicit 'use this when X, use list_accounts when Y' routing guidance even though google_ads_list_accounts and google_ads_account_info are close siblings. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real behavioral context beyond them: the 30-day per-call ceiling and the Business/Creator account requirement, both of which affect whether a call will succeed.

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; the metric list is compact and the limiting constraint ('Max 30 days per call') is placed at the end where it is easy to scan. 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?

With no output schema, the description usefully enumerates the returned metrics (reach, views, profile visits, engagement, likes, comments, saves, shares, website taps, follower count, net new followers), covering what the agent would otherwise not know. Defaults and precedence for the date parameters are in the schema, so nothing material 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 all four parameters are already documented, including the defaults and the since/until precedence. The description only reinforces the 1-30 day constraint, adding marginal value over the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Get analytics for your own Instagram Business/Creator account') plus an explicit scope constraint (account-level, own account) and enumerates the exact metrics returned. An agent can distinguish this from instagram_media_insights (per-post) without opening either schema.

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

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

The 'your own Business/Creator account' scoping and the 'Max 30 days per call' cap imply when the tool is valid, but there is no explicit when-to-use guidance or named alternative for per-media stats (instagram_media_insights). Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: it enumerates the returned metrics (reach, views, likes, comments, saves, shares, permalink) and discloses that Stories are included, which is non-obvious. It stops short of mentioning insight-fetch cost/latency or ordering guarantees.

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 packs verb, resource, scope, and payload into minimal space with zero filler. Nothing is repeated or wasted.

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

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

With 100% schema coverage and no output schema, the description usefully compensates by naming the returned metrics. It is largely complete for a simple list tool, though it could have disambiguated itself from the adjacent instagram_*_insights tools.

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

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

Schema description coverage is 100%, so all three parameters (limit, with_insights, instagram_account_id) are already fully documented in the schema, including defaults and the faster-path tradeoff. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (your own Instagram posts, Reels, Stories) plus the payload (per-post insights with named metrics). The 'your own latest' scope implicitly separates it from search_instagram, but it never names a sibling to make the distinction 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?

There is no when-to-use or when-not guidance. With siblings like instagram_media_insights, instagram_account_insights and search_instagram in the catalog, an agent gets no help deciding which to call or in what order.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful ownership constraint ("your own") but does not describe the returned insights or any rate-limit/permission behavior.

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 with zero filler, stating verb, resource, scope, and the id source all at once.

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 read tool with one parameter and no output schema, the description plus annotations cover what an agent needs: safety, target scope, and where the id comes from. It stops short of describing the insight fields returned, which a caller might still want.

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

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

Schema coverage is 100% and there is a single required media_id already documented in the schema. The description adds only the provenance hint (from instagram_list_media), 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?

The description names a specific verb (Get), resource (insights), and scope (one of your own Instagram posts, Reels or Stories), which clearly separates it from the sibling instagram_account_insights (account-level) and pairs with instagram_list_media. An agent can pick this tool 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?

It tells the agent the required input is a media id obtained from instagram_list_media, which is practical routing context. However, it does not explicitly state when to prefer this over instagram_account_insights or what to do when the media isn't your own, so no full when-not guidance.

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

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

Consistent with readOnlyHint=true and destructiveHint=false; nothing contradicts the annotations. Beyond the annotations it adds real behavioral context: the response contains click-by-click steps, exact links and screenshots, and the agent is expected to drive an interactive collection flow. It doesn't mention pagination or size limits, which is minor for a static guide.

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 core purpose and the read-then-guide workflow are front-loaded in the first sentence, with the provider hint last. It is on the longer side with some repetition of the provider list already in the schema, but no sentence 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 carries the return-value burden and does so adequately by describing the guide's contents. For a two-parameter read-only tool, an agent has enough to select and invoke it, though a pointer to connect_integration as the follow-up step would close the loop.

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

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

Schema coverage is 100% and both parameters are already documented, including where the integration id comes from. The description mostly restates the provider value list and adds only a small timing cue ('once you know it'), which is useful but marginal against a fully documented 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+resource: fetching a step-by-step walkthrough for connecting an account to Lodestone, including what it contains (links, screenshots, values to collect). It implicitly separates itself from the mutation sibling connect_integration by framing this as read-then-guide, but never names that sibling, so differentiation is inferred rather than stated.

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

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

It states clear usage: read the guide, then walk the user through it one step at a time and collect values in chat, and it explains when to pass the provider ('once you know it'). It stops short of explicitly telling the agent to call integration_status first or connect_integration afterward, leaving the lifecycle relationship to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond the annotations by stating the return is scoped to connection status and includes no credentials, though it does not describe the exact response 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?

The description is two tight sentences with the core purpose and ordering guidance front-loaded. Every clause adds either scope, usage guidance, or a security-relevant return constraint.

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 read-only status tool with no output schema, the description provides enough: what it checks, when to call it, the provider scope, and that credentials are not returned. Annotations already cover the safety profile, so no critical context 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 there is nothing for the description to disambiguate. The baseline for a parameterless tool is 4, and the description correctly avoids implying any required input.

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: show which of the user's own accounts are connected versus not. It enumerates the integration providers and clearly distinguishes this status check from connect_integration and disconnect_integration.

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

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

Gives explicit trigger conditions: call first when the user wants to connect something, or when another tool reports an account is not connected. This directly routes the agent between this diagnostic tool and the connect/disconnect siblings.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by naming the response contents (currency, status, lifetime spend, spend cap, balance), which matters because there is no output 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?

A single front-loaded sentence that names the action and immediately enumerates the returned fields. No preamble or filler.

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

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

For a one-parameter read tool whose annotations cover the safety profile, listing the returned fields compensates for the missing output schema. Only the absence of routing guidance against sibling account tools leaves a small 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?

One optional parameter with 100% schema coverage, where the schema already documents the act_XXXX format and the default-to-connected-account behavior. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get details for your Meta ad account') and enumerates the fields returned, so the agent knows what it retrieves. It does not explicitly differentiate itself from close siblings like meta_ads_list_accounts or meta_ads_whoami, which keeps it from 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 description gives no when-to-use guidance, no conditions, and no alternatives. With siblings such as meta_ads_list_accounts and meta_ads_whoami in the same family, the agent must infer that this is the single-account detail call.

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 declare the generic write/open-world profile (readOnlyHint=false, destructiveHint=false). The description adds meaningful behavior: it impacts the live account, the created ad defaults to PAUSED, and it enforces a confirm:true safety gate. That said, 'PAUSED default' and 'confirm' partly overlap with schema descriptions, so it is strong but not fully additive.

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 opens with the [WRITE — changes your live account] warning, then delivers scope, precondition, default state, and the confirm requirement with zero wasted words.

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

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

With no output schema, the safety annotations present, and full schema coverage, the description supplies everything an agent needs: purpose, write impact, precondition, default status, and the confirm gate. Nothing required 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 all five parameters (including post_id format and ad_set_id provenance) are already documented in the schema. The description corroborates 'existing ad set' and 'confirm:true' but adds no syntax or semantic detail beyond the schema — the baseline 3 applies.

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

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

States a specific verb (promote/boost), resource (existing Facebook Page post as an ad), and the key scoping distinction '(no upload)' plus 'under an existing ad set'. This clearly separates it from the sibling meta_ads_create_image_ad without needing to open either schema.

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

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

Implies the preconditions that an ad set must already exist and that the post already exists (no upload path), steering the agent away from the create/upload siblings. However, it never names an alternative tool or an explicit when-not-to-use condition, so it falls short of full routing guidance.

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