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

Annotations only declare readOnlyHint=false, so the description carries most of the behavioral burden. It usefully discloses that advanced/paid options are left at server defaults, but says nothing about error behavior, permission requirements, or whether creation is idempotent.

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 short sentences with no filler, front-loaded with the core purpose and then the requirements. Nothing is repeated from the schema verbatim; the sentences each add something.

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

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

For an 8-parameter mutation tool with no output schema, the description is serviceable but incomplete: it omits the actionType/dailyCap/keyword options and does not say what is returned (e.g., the new automation id) for follow-up calls.

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 0%, so the description must compensate, and it covers the four required fields plus the igAccountId source and the {{handle}}/{{commentText}} template tokens. It leaves the four optional params (actionType, dailyCap, includeKeywords, excludeKeywords) and both enums unexplained.

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 with a distinguishing qualifier ('comment→DM automation'), so an agent can separate it from create_broadcast and update_automation. It does not name a sibling explicitly, but the resource plus trigger scope 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?

It lists the required parameters and points the agent to list_ig_accounts as the source of igAccountId, which is a real workflow hint. However, there is no when-to-use vs when-not guidance, nor any mention of how this differs from update_automation or when a new automation is appropriate.

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

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

Annotations only declare readOnlyHint=false, so the description carries real weight here and delivers the key trait: this creates a draft and does not send, which is exactly the behavioral distinction an agent needs before invoking. It adds the mutual-exclusivity constraint on audience params but says nothing about permissions, limits, or what happens to mediaAssetIds.

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

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

Three tight sentences with the draft/not-send constraint front-loaded, followed by the audience rule and the routing hint. No filler and no restatement of the name or 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?

Covers the highest-risk aspects for this tool: the draft semantics, the audience exclusivity rule, and the handoff to send_broadcast. The nested filter object is given an example, which is helpful, but the definition is still silent on four parameters and there is no output schema to fill the 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 0% across 7 parameters, so the description must compensate and only partly does: it explains segmentId, filter (with a concrete {minScore:50} example), and the format default of TEXT. The three required parameters (name, igAccountId, templateText) and mediaAssetIds (including its maxItems of 10) are left entirely undocumented.

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 DRAFT broadcast') and immediately scopes it with '(does NOT send)', which separates it from send_broadcast and list_broadcasts in the sibling set. An agent can route to this tool without opening any schema.

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

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

Gives explicit when-to-use routing ('Use send_broadcast to send it') and a hard selection rule for the audience ('Provide exactly one audience: segmentId OR filter'). It doesn't address how this differs from create_automation, which is a plausible confusion in this sibling set, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known before reading the text. The description reinforces this with 'Permanently' and 'cannot be undone', which is modest added value, but it says nothing about required permissions, whether dependent data (leads, logs, broadcasts) is cascaded, or how failures are reported.

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 permanence warning front-loaded right after the core action. Nothing could be removed 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 single-parameter destructive tool with annotations covering the safety signal and no output schema, the definition is nearly sufficient. The only real gap is the absence of any note on cascading effects or permission requirements before an irreversible operation.

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

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

There is one parameter with 0% schema description coverage, so the schema documents only type and pattern. The phrase 'by id' identifies the argument's role as the target automation but adds no format, sourcing, or lookup guidance beyond the schema's regex pattern.

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 ('Permanently delete an automation by id'), which unambiguously separates it from the sibling tools update_automation, get_automation, and create_automation. An agent can select it without opening any schema.

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

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

The description gives no explicit when-to-use framing, no prerequisites, and does not point to update_automation as the non-destructive alternative. Usage is only inferable from the verb 'delete'.

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, so the safety profile is covered. The description adds only the return format (CSV text); it says nothing about size limits, row caps, whether the export is synchronous or paged, or whether it honors any account scoping. For a bulk export where volume matters, this is a modest but not complete 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?

A single front-loaded sentence with no filler, stating action, scope and format. It is efficiently sized, though the extreme brevity means it spends no words on the operational caveats an export tool usually 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 parameters, no output schema, and readOnlyHint already set, the structured fields carry most of the load. Still, a bulk export tool leaves real questions unanswered: whether the CSV is returned inline or as a file/link, and whether very large result sets are truncated.

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 and the schema is trivially complete, so there is nothing for the description to clarify. Baseline 4 applies; the description's implicit claim that the export is unfiltered is consistent with an empty parameter set.

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 plus the output format: 'Export all leads as CSV text.' An agent immediately knows this is a bulk data dump rather than a filtered read. It does not, however, distinguish itself from the sibling list_leads, which reads similar leads data in a presumably different shape.

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 choose this over list_leads, get_lead, or the other lead-reading siblings. The phrase 'all leads' implies no filtering, but the description never says so explicitly nor names an alternative for filtered retrieval.

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

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

readOnlyHint=true already establishes the safety profile, so the description is only required to add context beyond that. It does so by naming the exact scope (authenticated account, not arbitrary accounts) and the returned content, 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 with no filler, and the scope qualifier ('authenticated') appears before the field list so the agent reads the constraint 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?

For a parameterless read tool, the description covers scope and payload, which largely compensates for the absent output schema. It stops short of noting quota/usage semantics or anything about caching or freshness, but nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. No misleading parameter hints are given.

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 (Return) and a precisely scoped resource (the authenticated ReplyAtlas account), then enumerates the payload: profile, plan tier, DM quota/usage, feature flags. That is enough to separate it from neighbors like list_ig_accounts or get_dashboard, though it never states that distinction 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_dashboard or list_ig_accounts. The agent must infer that this is the tool for reading its own account context.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. Beyond that the description adds nothing behavioral: it does not say what happens when kind/range are omitted (both are optional), whether a default is applied, or what shape the response takes despite there being 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?

Two short, front-loaded sentences with no filler; the lead clause states the purpose and the value lists follow. It is efficient, though so terse that it borders on under-specification for a six-variant parameter.

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

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

With no output schema and zero required parameters, the description should explain defaults and return content per kind, and it does neither. For a tool whose whole value is the kind/range combination, this is materially incomplete.

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 0%, so the description must carry the burden, and it does restate the allowed values for both enums. However, those values are already present in the schema enums, and it never explains what each kind actually returns or how range interacts with kind.

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 the resource (analytics) and enumerates the six breakdown kinds, so an agent knows it retrieves analytics data broken down by dimension. It does not differentiate itself from the sibling get_dashboard, which is also an analytics/read tool, leaving ambiguity about which 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?

There is no explicit when-to-use guidance, no statement of when not to use it, and no mention of the sibling get_dashboard. The kind enum implies what can be requested but the agent gets no criteria for choosing this tool over the dashboard tool.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description adds almost nothing behavioral — no not-found/error behavior, no auth or scope requirements, no note on whether it returns the full record. It essentially restates the name and annotations.

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

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

One short, front-loaded sentence with no filler. It is concise, though at the cost of any detail beyond the bare operation.

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

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

For a one-parameter read tool with a readOnly annotation and no output schema, this is minimally adequate; return shape needn't be described, but missing not-found handling and identification of the id source leave real gaps.

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

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

The single parameter is documented at 0% coverage in the schema (only a regex pattern, no description). The phrase 'by id' confirms the id is the record selector, which is modest added value, but it gives no format, source, or example for obtaining the id.

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?

Contains a specific verb ('Fetch'), a clear resource ('automation'), and a scope qualifier ('a single ... by id') that implicitly separates it from list_automations. It does not explicitly name the sibling, but the singular-vs-list distinction is derivable.

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?

No guidance on when to use this over list_automations, update_automation, or get_lead/get_account. Usage is only implied by 'by id' — an agent must infer that it needs a known automation id and that this is the read-a-single-record path.

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

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

readOnlyHint=true already establishes this is a safe read. The description goes further by naming the payload contents (DMs sent, leads, conversions) and the accepted range modes, which is genuinely useful given there is no output schema. It stops short of noting permissions, timezone, or default behavior when range is omitted.

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 packed sentences with the payload description front-loaded and the parameter rules following immediately. No filler, no redundancy.

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

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

For a 3-parameter read tool with no output schema, the description covers the metric payload and the range/from/to contract well. The remaining hole is default behavior when range (optional, no required params) is omitted, plus timezone semantics for the ISO dates.

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 0%, so the description carries the burden — and it largely does, enumerating all five range values and specifying that custom requires from/to as ISO dates. The one gap is that 'to' is only covered by the 'from/to' pairing rather than stated explicitly.

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 ('Dashboard snapshot') and even enumerates the returned metrics (DMs sent, leads, conversions), which is more than the title restates. It does not, however, differentiate itself from the nearby sibling get_analytics, so an agent cannot tell the two apart from the description alone.

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 through the range enum and the 'for custom, also pass from/to' rule, which tells the agent how to call it in each mode. There is no explicit when-to-use guidance, no statement of defaults, and no routing to or away from alternatives such as get_analytics.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds the useful behavioral note that the response 'includes activity', which is non-obvious since there is no output schema, but it omits any error/not-found behavior or payload 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?

A single short sentence with the resource and lookup key front-loaded and zero filler. Nothing could be trimmed without losing information.

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

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

For a simple read tool with annotations and no output schema, the description is adequate: it names the operation, the key, and that activity data is included. It does not describe the returned lead fields, error cases, or authorization requirements, leaving some gaps.

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

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

Only one parameter, and the schema provides no description for it (0% coverage). The phrase 'by id' tells the agent the argument is a lead identifier, which is minimal but meaningful added context; it does not clarify format, source, or whether it accepts external IDs.

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 ('Fetch') and resource ('a single lead') scoped by id, which implicitly distinguishes it from the sibling list_leads. It stops short of explicitly naming that alternative, so it is clear but not fully differentiated.

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 'single' plus 'by id' implies the tool is for retrieving one known lead rather than enumerating them, so usage is inferable. No explicit when-to-use statement or named alternative (e.g., list_leads for browsing) is given.

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

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

readOnlyHint=true already declares this as a safe read, so the safety burden is lifted. The description adds useful behavior by disclosing the pagination contract and the nextCursor handoff, which the annotations do not cover, but it says nothing about result ordering, page size defaults, or 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 tight sentences with zero filler; the resource and its paginated nature are front-loaded before the cursor mechanics. 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 paginated list tool with a readOnly annotation and no output schema, the description covers the core action and the pagination loop. The only real gap is the undocumented limit parameter and lack of any hint about the returned automation shape.

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 0%, so the description must compensate. It explains cursor semantics well (source it from the previous response's nextCursor), but the limit parameter — including its 1–100 range — is left entirely undocumented.

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 a specific resource (comment→DM automations), plus the pagination nature. This distinguishes it from generic list siblings like list_tags or list_leads, though it does not explicitly contrast with get_automation or list_dm_logs.

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

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

Provides clear operational guidance for pagination ('Pass cursor from the previous response's nextCursor to page'), which is genuine usage instruction. However, there is no guidance on when to prefer this over get_automation or list_dm_logs, and no stated prerequisites.

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=true, and the description adds two pieces of genuine behavioral context beyond that: the result ordering ('newest first') and an entitlement precondition (Pro plan / BROADCAST). It stops short of describing pagination or result limits, which would be needed for 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, zero waste, with the core action and ordering front-loaded and the plan requirement appended where it belongs.

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 tool with no output schema, the description covers what it returns conceptually (a list of broadcasts), the ordering, and the plan gate. Only pagination/volume behavior is unaddressed, a minor gap given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter surface for the description to clarify or omit.

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 account's broadcasts'), which clearly separates it from the mutating siblings create_broadcast and send_broadcast. It does not explicitly name or differentiate against any sibling, so it falls short of the 5 benchmark.

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 obvious use case (enumerate existing broadcasts) and adds an eligibility gate ('Requires the Pro plan (BROADCAST)'), but it never states when to prefer this over list_tags/list_automations or how it relates to create/send_broadcast. 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, so the safety profile is covered. The description usefully adds that results are paginated and that a plan entitlement gates access, but says nothing about ordering, page size behavior, or what a cursor represents.

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 core action and no filler. Efficient overall, though the parenthetical '(paginated)' could have carried the cursor/limit detail it hints at.

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

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

With no output schema and zero parameter documentation, the description should do more than name two filters. It covers the entitlement prerequisite and pagination existence but leaves the agent guessing about limit bounds and cursor semantics.

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 0%, so the description carries the full burden and only names two of four parameters (igAccountId, unreadOnly). The limit parameter's 50-item cap and the opaque cursor string are left completely undefined in both description and schema.

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

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

States a specific verb and resource ('List human-agent inbox conversations') with scoping detail that separates it from a raw message log. It does not, however, name or contrast with the nearest sibling (list_dm_logs), leaving the agent to infer the boundary.

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

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

The only usage-shaped content is the prerequisite that the plan must include the human-agent inbox. There is no guidance on when to choose this over list_dm_logs or when to reach for reply_to_conversation after listing.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds the pagination mechanism and the status vocabulary. It says nothing about default ordering, result volume, or how an exhausted cursor behaves, so the added behavioral context is modest.

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 segments, resource and pagination front-loaded, then filters. Every clause carries information and nothing is 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?

Covers filtering and pagination adequately for a five-param list tool with no output schema, but omits limit semantics, ordering, and any indication of what a log entry contains, which an agent may need to use results 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 0%, so the description carries the burden and largely delivers: it explains q, automationId, cursor, and crucially supplies the comma-separated status enum values that the schema omits. It does not mention the limit parameter or its maximum of 200, leaving one of five params undocumented.

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 sent-DM logs') and scopes it to sent DMs, which distinguishes it from siblings like list_conversations and list_broadcasts. It never names an alternative tool to route against, 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 filter list implies the intended retrieval contexts (by automation, by delivery status, by search term), but there is no explicit when-to-use or when-not-to-use guidance and no pointer to a sibling for related data.

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

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

readOnlyHint=true already declares this as a safe read operation, so the description's disclosure of returned fields (id, handle, followers) is the main added value. It says nothing about authentication, pagination, or what happens for accounts with no connection, so it is adequate but not rich beyond the annotation.

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, front-loaded with the action and resource, then the returned fields, then the practical follow-up. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so by listing the three exposed fields. For a zero-parameter list tool this is fully sufficient for correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4. The description still usefully names the identifier field ('id') that flows into `igAccountId` elsewhere, which is meaningful context even though no input schema exists to document.

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 connected Instagram accounts') and even enumerates the returned fields (id, handle, followers). It is trivially distinguishable from siblings like list_tags, list_leads, and list_automations, which cover different resources.

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

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

The second sentence gives a downstream usage hint ('Use an id as `igAccountId` when creating automations or broadcasts'), which implies why an agent would call this. However, it never states when to prefer this tool over alternatives or any precondition (e.g. account must be connected), so guidance is only implied.

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, so the safety profile is covered. The description adds genuine behavioral context by disclosing pagination and the cursor/nextCursor contract, which is beyond the annotations, but it says nothing about auth requirements, rate limits, or default/max page size.

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 resource and filter semantics front-loaded and no filler. The parenthetical filter dump is dense but every clause earns its place, aside from the slightly cramped phrasing of the pagination 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?

No output schema exists, but the description explains the return-time pagination contract (cursor from nextCursor), which is the key missing piece. The main residual gap is limit/default page size and lack of any sibling routing guidance for a tool with 20 siblings.

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 0%, so the description carries the full burden, and it does most of the work: it defines the score range (0–100), the sentiment enum values, converted semantics, and that q searches handle/name and tag is a tag id. It omits meaning for limit and only partially explains cursor, so it is strong but not complete.

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/filter leads') and notes it is paginated. It does not explicitly differentiate from siblings like export_leads or get_lead, though the list/filter framing implicitly separates it from the single-lead getter.

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 filter list implies when to use it (browse/segment leads), but there is no explicit when-to-use vs when-not guidance or named alternative such as export_leads or get_lead. Usage is implied 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, so safety is covered. The description adds value beyond annotations by disclosing the return shape ('id + name') in the absence of an output schema, though it says nothing about ordering, pagination, or account scope.

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, front-loaded with the purpose and followed by the actionable follow-up. Every clause earns its place with no filler or restatement of 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?

A zero-parameter read tool with no output schema is fully covered: the description states what is listed, what fields come back, and how to use those ids elsewhere. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is no argument surface that the description needs to explain.

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 account's lead tags') and immediately scopes the output as 'id + name'. It is clearly distinguishable from siblings like list_leads, get_lead, and tag_lead.

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 tells the agent what to do with the result: pass a tag id to tag_lead or the list_leads `tag` filter. It gives clear downstream context but does not state when this tool should not be used or any prerequisites (e.g., empty list behavior).

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 the critical detail the annotations cannot convey: the first call does not send, it only returns a preview plus a confirmToken, and the send only happens on the second call. It also discloses the inbox-plan requirement. This is exactly the behavioral context an agent needs to avoid an accidental irreversible send.

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, and the core action plus the two-step safety protocol are front-loaded. The SAFETY marker makes the non-obvious requirement scannable.

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

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

For a destructive mutation with no output schema, the description covers the key return value (preview + confirmToken) and the auth/plan prerequisite. It could go slightly further by stating that a confirmed send is irreversible and cannot be undone.

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 only 33% (confirmToken documented, id and text not). The description partially compensates by explaining the required confirmToken echo and that id/text must be identical across both calls, but it says nothing about the id format or the 1000-character text limit.

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 ('Send a DM reply in a conversation'), which is clearly distinct from the broadcast siblings (create_broadcast, send_broadcast) and from list_conversations. It does not explicitly name an alternative, 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?

Gives precise invocation guidance: call once with {id, text} for a preview, then call again with the same id, text, AND confirmToken to actually send. It also states the plan prerequisite. No explicit when-not or named alternative, but the procedural context is unusually clear.

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

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

Annotations already indicate this is not read-only and is destructive, but the description adds critical behavioral context: the two-step preview/confirm safety flow, recipient count preview, confirmToken issuance, and the Pro plan requirement. This is exactly the kind of extra operational detail annotations cannot convey.

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

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

Three sentences, front-loaded with the purpose and immediately followed by the safety workflow. Every sentence earns its place and there is no redundant restatement.

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, two-step send operation with no output schema, the description covers the essential workflow, safety requirement, and plan constraint. The preview output (recipient counts and confirmToken) is explained, and the final send action is unambiguous.

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 only 50% schema description coverage, the description carries more weight and explains both parameters in context: broadcastId selects the draft, and confirmToken from the preview is required to actually send. It does not explain the broadcastId pattern or all edge cases, but it substantially compensates for the schema gap.

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

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

The description states a specific verb and resource: sending a DRAFT broadcast to its audience. It clearly distinguishes the tool from creation/listing siblings such as create_broadcast and list_broadcasts, and the two-phase preview/send workflow further sharpens its identity.

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 operational guidance: call once for preview and a confirmToken, then call again with both to send. It also states the Pro plan requirement. It does not name alternative tools or when not to use this one, so it falls short of a full 5.

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

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

Annotations only declare readOnlyHint=false, so the description bears most of the burden. It usefully clarifies that this is a pure attachment that never creates a tag, but says nothing about duplicate-tag behavior, idempotency, failure modes, or required permissions for a write 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?

Two short sentences, action first, constraint second. Nothing is padded and no sentence is redundant.

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

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

For a two-required-param mutation with no output schema and minimal annotations, the description covers purpose and the tagId source but omits what `id` denotes and how failures or duplicates are handled — gaps an agent would want before invoking a write.

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 0%, so the description must carry the load; it explains `tagId`'s provenance well (must be an existing id from list_tags). However, the `id` parameter — the target lead — is only implied by 'to a lead' and never named or constrained.

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 (attach) and resource (tag→lead), and explicitly excludes the adjacent operation of creating tags. An agent can distinguish this from any create/list sibling 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 a clear precondition — `tagId` must come from list_tags — which routes the agent to the right prerequisite tool. It doesn't discuss when-not to use it (e.g. what to do for a tag that doesn't yet exist), but the context is otherwise 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 only declare readOnlyHint=false, so the description must carry the behavioral load. It usefully discloses the partial-update contract ('only provided fields change') and the pause/resume semantics of `active`, but says nothing about permissions, whether an update can fail or be reversed, or what happens to related fields (e.g. templateText when actionType changes).

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, no filler, and the core update contract is front-loaded before the pause/resume tip. Every sentence contributes information an agent 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?

The highest-risk behavior for a mutation tool — partial update semantics — is covered, along with the active toggle. However, with 9 undocumented parameters, no output schema, and only a readOnlyHint=false annotation, the definition leaves large gaps around required identifiers, field interactions, and failure behavior.

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

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

Schema description coverage is 0% across 9 parameters, so the description is the only source of meaning and it covers just one field (`active`). The required `id` parameter is never explained, and no guidance is given on dailyCap, actionType/triggerType enums, templateText, or the include/exclude keyword arrays.

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 ('Update fields on an existing automation'), which clearly separates it from create_automation and delete_automation in the sibling list. It stops short of explicitly naming or contrasting those siblings, but the purpose 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?

It states when the tool is applicable at the field level ('only provided fields change' implies PATCH-style usage) and gives explicit how-to for the pause/resume case via `active`. It never says when to prefer this over create_automation or delete_automation, nor are prerequisites or conflict cases addressed, so guidance is implied rather than stated.

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