Inrō MCP for Instagram

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds useful behavior (writes are actively refused rather than silently ignored, and `get` returns trigger rules, account data, behavior, knowledge items, actions and tracked properties), but it then describes mutation actions and their required params as if they were usable here, which actively misleads about what the tool will do.

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 read-only disclaimer and action list are well front-loaded, but roughly half the text describes update/create/delete operations the tool refuses — content that belongs to the sibling agent_manage and serves only to confuse. The valuable part of the definition could fit in two sentences.

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 schema is extremely rich (every param is documented with action tags), so the description carries little burden, and the first paragraph supplies the routing and read-action coverage an agent needs. The duplication of agent_manage's write surface is not a gap so much as noise, but it does leave the overall definition ambiguous about this tool's actual capability 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%, so the baseline is 3 regardless of the description. The description does add a little meaning (what `get` returns, create_contact_property needing exactly one of field_name/contact_property_id), but most of its parameter detail maps to actions this tool does not expose, and it conflates 'list_items / create_item (params: item_type [required])' when the schema marks item_type as create_item-only.

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 line is precise — 'Read agent — this tool changes nothing' — and names the four supported read actions, which clearly separates it from agent_manage. However, the second paragraph opens with 'Manage the AI agent configuration' and enumerates update/create/delete operations, so an agent skimming the definition could conclude this tool can write.

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 routing rule is explicit and front-loaded: anything that writes is on `agent_manage` and is refused here, with the exact list of write actions named. There is no guidance on which read action to pick for a given goal, but the when-to-use-this-vs-alternative condition is stated clearly.

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 this as a non-read-only, destructive, non-idempotent, open-world mutation tool. The description adds some useful behavioral context, such as update changing only provided fields and rules replacing the whole rule list. However, it also describes unsupported read actions, which reduces trust in its behavioral 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?

The description opens with a duplicated action list, then repeats itself in a second paragraph with an overlapping action summary. The front-loaded mutating action list is undercut by later mention of read actions not in the enum. It is structurally redundant and includes conflicting 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?

The tool is complex with many nested action parameters, so accurate action-scope guidance matters. The description covers sub-resources but incorrectly includes get and list actions that the schema does not support, which could cause invalid calls. The schema is rich, but the description's scope errors leave it 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 100%, so the schema already documents the action params and per-action requirements in detail. The description repeats required parameters for create_item, update_item, and create_action but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description identifies the tool as managing the AI agent configuration and its sub-resources, and lists mutating actions. However, it also describes read actions like get and list_items even though the action enum excludes them, and it separately says reading belongs to the `agent` sibling. The core purpose is discernible, but the scope is muddled.

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 explicitly says reading operations are on the `agent` tool, which is useful routing guidance. But the second paragraph then describes get/list actions as part of this tool, undermining the when-to-use distinction. Per-action requirements are provided, but the read/write split is contradictory.

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, idempotentHint and destructiveHint, so the safety bar is partly met. The description still adds real behavioral context: writes are refused at this entry point, list results are ordered most-recent-first, and get returns current progress rather than a static snapshot.

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 key constraint (read-only, writes refused) is front-loaded correctly, but the text is materially redundant: "this tool changes nothing", "Read-only", and "is refused here" all make the same point, and "Read batch_tasks" opens both paragraphs. The empty parentheses artifact also costs clarity.

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 useful work by describing what get returns (current progress) and what list is ordered by. Remaining shortfall is that `batch_tasks_manage` is cited as the write alternative but does not appear among the available sibling tools, leaving the escape hatch ambiguous.

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 parameter meanings are already documented per action, including the enum values for status and task_type. The description restates the per-action parameter sets and adds only the most-recent-first ordering detail, 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?

The description names a specific verb+resource pair ("Read batch_tasks") and enumerates the two supported actions, list and get. It also explicitly distinguishes itself from the write sibling `batch_tasks_manage`, so an agent can route without opening either schema.

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

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

It states positively when this tool applies (reads, progress checks, e.g. campaign sends and bulk contact updates) and negatively that write operations belong to `batch_tasks_manage` and are refused here. The only gap is the empty parentheses in "Anything that writes ()", an unfilled placeholder that leaves the refused-write list unstated.

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 and destructiveHint=false, and the first sentence agrees ("this tool changes nothing"). The second paragraph, however, describes mutating and destructive behavior ("delete_campaigns permanently deletes them"), which conflicts with those annotations and with the stated refusal of writes. The read-only framing is stated, but the contradictory write/delete narrative undercuts behavioral clarity.

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 first two sentences are tight and front-loaded, but the second paragraph is a full specification of a different (manage) tool and does not belong here. Roughly half the description is irrelevant or misleading content for a two-action read tool.

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

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

For a read-only list/get tool with full schema coverage, full annotation coverage and no output schema, the first paragraph would be sufficient context. The extraneous manage paragraph introduces uncertainty rather than filling any genuine gap.

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

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

Schema description coverage is 100% and the schema already documents id, name, action_type and description per action, so the description's parameter listing adds little beyond it. Worse, most of the parameter detail it does provide relates to create/update/delete/duplicate, which are not valid actions in this schema; the only useful added signal is the "purely organisational" note about folder membership.

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 line gives a specific verb+resource ("Read campaign_folders") and names the sibling that handles writes, so an agent can distinguish it from campaign_folders_manage. However, the second paragraph restates a "Manage campaign folders" purpose with create/update/delete/duplicate actions that this tool does not expose, which muddies an otherwise clear purpose.

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

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

Strong explicit routing in the first paragraph: list/get here, anything that writes "is on `campaign_folders_manage` and is refused here." But the second paragraph then gives usage details for create, update, delete and duplicate on this same tool, contradicting that routing and leaving the agent unsure which guidance applies.

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 genuinely non-obvious behavior beyond that: folders are 'purely organisational — membership has no effect on how/when campaigns send', delete's `action_type` distinguishes ungroup (keeps campaigns) from delete_campaigns (permanent deletion), and duplicate 'copies folder + campaigns as drafts'. What it omits is any statement about permissions or whether duplicate's drafts are active/paused.

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 opening two lines and the subsequent paragraph are near-duplicates, restating the action list and the read/mutate split twice, and the second restatement contradicts the first. The per-action parameter parentheticals are dense and information-rich, but the redundant, inconsistent opening wastes the most valuable position in the description.

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

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

There is no output schema, and the description compensates for the riskiest paths by explaining what delete does to member campaigns and what duplicate produces (drafts). For a nested-parameter mutation tool with strong annotation coverage, that is close to sufficient; only the internal inconsistency about read actions and the absence of any permission/error context keep it from being complete.

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

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

Schema description coverage is 100%, and each nested field already documents which actions it applies to, so the schema carries the parameter burden. The description largely restates that mapping (id [required] for get/update/delete/duplicate; name [required] for create) rather than adding new meaning, so the baseline of 3 is appropriate.

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

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

The description names the resource and enumerates the mutating verbs (create, update, delete, duplicate), and it explicitly routes read operations to the sibling tool `campaign_folders`, so an agent can distinguish the pair without opening either schema. However, it undercuts itself by then listing 'list (index); get' among this tool's actions, which the schema enum excludes (only create/update/delete/duplicate), leaving ambiguity about whether reads are actually available here.

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

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

It gives an explicit routing rule: reading (list, get) belongs to `campaign_folders`, implying this tool is for mutations. That is clear context for selection, but it is immediately contradicted by the later enumeration that includes list/get, and there is no guidance on when to choose `duplicate` versus creating a new folder from scratch.

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 read-only posture is reinforced ('changes nothing', writes 'refused here'), which matches the readOnlyHint/idempotentHint annotations. But most of the text then details behavior of operations this tool cannot perform — send batch_task_id, test sending to a real contact, resend preview/confirm and activation quota consumption — which is noise that could mislead an agent into expecting those actions. For a three-action read tool it should describe the read behavior (pagination, funnel window semantics) instead.

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 correct framing is front-loaded, but roughly half the text is spent documenting create/update/send/test/resend in detail for a tool that refuses them. That is not conciseness — it is wasted tokens that also increase the risk of an agent attempting an unsupported action.

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 tool with no output schema, the description should focus on what list/get/performance return and how the funnel window behaves. `performance` is described well, but `list` pagination/sort semantics and `get` response content are not, while a large amount of space goes to irrelevant write paths.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the description's per-action param recap (page, per_page, status, search, campaign_folder_id, id, since, until) largely duplicates it. The one genuine addition is the explanation of what `performance` returns per step (sends reached, finished, reason codes), which gives meaning the schema lacks.

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 line is excellent: 'Read campaigns — this tool changes nothing' with explicit routing of writes to `campaigns_manage`. But the second sentence then restates 'Manage campaigns' and enumerates create/update/send/test/resend among its 'Actions', which contradicts the first sentence and the schema enum of list/get/performance. The net effect is a purpose that is stated clearly and then muddied in the same breath.

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?

Strong explicit exclusion: writes belong on `campaigns_manage` and are refused here. However it also instructs 'Call get_action_types first when building actions', which only makes sense for the write tool, and gives no guidance on when to choose `list` vs `performance` vs the sibling `show_campaign`.

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, the description discloses important behavior: `update` is draft-only and rebuilds from the payload, `send` queues executions and returns `batch_task_id`, `test` really sends to one contact and is excluded from metrics, and `resend` previews by default unless `confirm` is set. It also warns that `confirm` consumes activation quota and messages real people, which is exactly the kind of context an agent needs for a destructive tool.

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 front-loaded with the core purpose and alternatives, but it is long and repeats the action list after already stating the mutating actions. The second action list also contradicts the schema, so the structure is less clean than it could be.

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

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

For a complex, destructive, open-world tool with no output schema, the description covers most action semantics and safety-relevant behavior well. It does not explain return values for most actions, and the mismatch between described actions and the schema enum leaves an important 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 is 3, but the description adds meaningful semantics: create has three modes, `template_id` is mutually exclusive with `actions` and `campaign_rules`, and update replaces the campaign from the payload. The main flaw is that it documents parameters for `list`, `get`, and `performance`, which the schema's `action` enum does not permit.

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 sentence states a specific verb and resource ('Change campaigns') and explicitly routes read operations to the `campaigns` sibling. However, the later action list includes `list`, `get`, and `performance`, which are read operations and are not in the input schema's `action` enum, muddying the tool's actual scope.

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

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

It gives clear when-to-use guidance: use this tool for mutations, use `campaigns` for reading, and call `get_action_types` first when building actions. The guidance is strong, but the inclusion of unavailable read actions weakens the routing signal.

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 and destructiveHint=false, yet the description describes delete ("irreversible, removes all values") and backfill ("spends AI credits") as actions of this tool. It also contradicts the schema, whose action enum contains only "list". The agent is told destructive semantics apply to a tool that cannot perform them.

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 front-loaded disclaimer is well placed, but the bulk of the text is boilerplate copied from the manage tool and is irrelevant to this tool. Roughly two-thirds of the description does not apply, making it both bloated and 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 single-action paginated read tool, little explanation is needed, and the disclaimer plus schema would nearly suffice. The appended write-action documentation instead introduces false capabilities, leaving the definition misleading rather than complete.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description's parameter detail is attached to actions (create/update/delete/backfill) that this tool cannot execute. The only real action, list, gets just "paginated index, params: page, per_page", which the schema already documents fully. The added text misleads rather than clarifies.

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 line does state a clear read-only scope: "Read contact_properties — this tool changes nothing. Actions: list." But the second paragraph immediately reframes the tool as "Manage custom contact properties" with create/update/delete/backfill, which contradicts the stated purpose and would confuse an agent about what the tool actually does.

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

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

Explicit routing is provided: writes are on `contact_properties_manage` and "is refused here." That is a genuine when-to-use/when-not instruction naming the correct sibling. The value is undercut by the following paragraph, which then documents those very write actions here.

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 past the annotations: delete is flagged irreversible and removes all stored values, backfill is described as running in the background against existing contacts without values, returns a batch task to poll, and consumes AI credits. These are exactly the operational side effects an agent cannot infer from `destructiveHint: true` alone.

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 competing opening sentences ('Change contact_properties. Actions: ...' and 'Manage custom contact properties. Actions: list...') plus a nested action list make the front matter redundant and partly wrong. The per-action detail blocks are well organized, but the duplicated preamble wastes the most-attended position in the description.

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 generic tool multiplexing four mutations over a nested action_params object, it covers destructiveness, async behavior, polling, credit cost, and cross-tool routing. Nothing critical is missing except clarity on the list action, which the tool does not actually support per the enum.

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

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

Schema description coverage is 100% and the schema already tags each param with its applicable actions ([create, update], [update, delete, backfill], etc.), so the description's per-action param lists are largely restatement. The only genuine addition is the explicit 'property needs auto_detect on' precondition for backfill, which the schema only hints at. 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?

Names a specific resource and enumerates the mutating actions (create, update, delete, backfill), and explicitly routes reads to the sibling `contact_properties`. That sibling naming is exactly the differentiation an agent needs. The score is capped by the opening contradiction: line one says actions are 'create, update, delete, backfill' and line three reintroduces 'list' as an action, which is absent from the schema enum.

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 per-action context and an explicit alternative for the read path ('Reading (list) is on `contact_properties`'), which is the main routing decision for this family of tools. It also states preconditions for backfill (auto_detect must be on). However, the resurrected 'list' action with page/per_page params conflicts with the schema and could lead an agent to call an unsupported action.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so 'this tool changes nothing' adds nothing. Worse, the description then documents update and bulk_update (including 'apply per-contact updates to up to 1,000 contacts asynchronously') as actions of this tool, which contradicts the read-only annotation and the schema enum. The only genuine added context is the async/1,000-contact note, which does not belong to this tool.

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 read-only constraint and action routing are front-loaded, which is good, but the second paragraph is a dense run-on enumerating every action and parameter, much of which duplicates the schema. It also repeats the destructive/read-only framing twice ('this tool changes nothing' and 'is refused here') while simultaneously documenting write actions.

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, 2-parameter wrapper over five actions with 100% schema coverage and no output schema, the definition covers every action's purpose, required params, prerequisites, and pagination knobs. The remaining gap is a self-inflicted one — the phantom update/bulk_update content — rather than missing information.

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 already documents most fields, but the description adds per-action parameter mapping, marks which params are required per action, and flags the ordering default difference for list_messages (desc on received_at vs asc elsewhere). It stops short of explaining filter object composition beyond pointing at get_contact_filter_types.

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

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

The first sentence states a specific verb and resource ('Read contacts') and the second enumerates the concrete actions (list, search, filter, get, list_messages) with their parameters, so an agent can tell it apart from contacts_manage. The clarity is undercut by the second paragraph, which reintroduces 'update' and 'bulk_update' as if they were actions of this tool even though the same description says writes are refused here.

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

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

Strong routing guidance: writes are explicitly delegated to contacts_manage, filter requires calling get_contact_filter_types first, list_messages is preferred over last_messages to read beyond the latest 10, and 'provide exactly one' of id/username/email is stated. The guidance is weakened by the contradictory listing of update/bulk_update as available actions, which gives an agent two incompatible usage models.

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, idempotentHint=false and destructiveHint=false, so the mutation profile is known. The description adds one genuinely new behavioral fact beyond the schema: bulk_update is applied 'asynchronously' (the 1,000 cap is already in maxItems). It says nothing about partial failures, whether bulk_update is reversible, or how to locate the async result, which matters for a non-idempotent bulk mutation.

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 nearly duplicate lead-ins ('Change contacts...' and 'Manage contacts...') plus a full spec of five read actions this tool cannot perform. The relevant content is two short clauses; the majority of the text is dead weight that actively misleads.

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-action mutating tool, the essentials (how to locate a contact, the async bulk semantics, the read-tool pointer) are present, and there is no output schema to explain. Completeness is undercut by the pasted read-action documentation, which inflates coverage of actions the tool does not support while leaving the async-result question unanswered.

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

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

Schema description coverage is 100% and the nested action_params/enum are exhaustively documented, so the description does not need to restate parameter detail. What it adds is mostly duplication of the schema ('provide exactly one of id/username/email', page/per_page/order params), and the 'call get_contact_filter_types first' hint applies to the `filter` action, which this tool does not implement.

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 'Change contacts. Actions: update, bulk_update' plus the pointer to `contacts` for reads is exactly what an agent needs and clearly separates this tool from its sibling. But the next block then re-declares 'Actions: list; search; filter; get; list_messages' with full parameter detail, contradicting the first sentence and implying this tool exposes read actions that its schema does not contain.

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?

'Reading (list, search, filter, get, list_messages) is on `contacts`' is an explicit routing rule to the alternative, and the per-action required-parameter notes (updates plus one of id/username/email; contacts for bulk_update) tell the agent how to invoke each action. No exclusions or prerequisites like permissions are stated, and the read-action prose muddies the routing it just established.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful refusal behavior, but then spends equal space describing mutation semantics (delete clearing message references) that this tool can never perform, which adds noise rather than transparency about this tool.

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?

Roughly half the text is a pasted block from conversion_links_manage's definition, enumerating create/update/delete parameters that are not reachable through this tool's enum. The genuinely useful content (read-only scope, list/get, sibling routing) is front-loaded but then buried under inapplicable detail.

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 tool is simple (2 top-level params, one enum) and annotations are rich, so little description is needed; the read-only scope plus the pointer to the manage sibling would suffice. The extra mutation paragraphs are not just surplus but potentially misleading for an agent that might attempt an unsupported action.

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 already carries a per-action applicability tag (e.g., "[get, update, delete] Conversion link ID"). The description only restates those same signatures, including signatures for actions the enum forbids, so it adds no meaning 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 opening clause is decisive: "Read conversion_links — this tool changes nothing. Actions: list, get." That is a specific verb+resource plus explicit sibling routing to conversion_links_manage. However, the second sentence block then enumerates create/update/delete with full param lists, re-muddying what the tool actually does.

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

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

Explicitly states that write operations belong to conversion_links_manage and are refused here, which is exactly the alternative-routing guidance an agent needs. It does not, however, say when to choose 'get' over 'list' or when list itself is the wrong tool (e.g., use search_templates instead).

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's real contribution is the concrete consequence of deletion: existing messages that used the link persist with the reference cleared. That is genuinely useful disclosure beyond the annotation flags. It stops short of covering auth requirements, reversibility of updates, or rate limits, so it is strong but not exhaustive.

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 opens with a throwaway duplicate ("Change conversion_links. Actions: create, update, delete.") before the substantive paragraph, and then spends roughly half its length enumerating list/get operations that this tool cannot perform. Front-loading is good, but a meaningful share of the text does not earn its place and actively misdirects.

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 non-idempotent, destructive, multi-action tool with a nested action_params object, the description adequately explains the resource and delete side effects. What it lacks is reconciliation with the schema enum — it advertises read actions that are not permitted — plus any note about permissions or what a successful mutation returns (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% and the schema already tags each field with its applicable actions, so the description's per-action parameter listing is largely restatement. It does usefully restate the per-action required combinations (create needs title+url+button_title), but it also documents `page`, `per_page`, `search`, and `id` for list/get in a tool whose enum only permits create/update/delete, adding misleading rather than clarifying 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 opening sentence gives a specific verb set (create/update/delete) on a named resource and explicitly routes reads to the sibling `conversion_links`, which is exactly the differentiation an agent needs. However, the second paragraph then re-enumerates `list` and `get` with their parameters as though they were available actions here, which undercuts the otherwise crisp scope statement and could lead an agent to emit an out-of-enum action.

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 names the alternative tool for reads explicitly ("Reading (list, get) is on `conversion_links`") and describes what a conversion link is, so the agent knows when this tool applies. The guidance is weakened only by the later sentence that reintroduces list/get as if callable, creating ambiguity about when to switch 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 readOnly/idempotent/non-destructive, and the description adds real substance beyond them: the 90-day aggregate window vs. by-id reads at any age, the reason_code vs. status_message distinction, and that action_data is the step configuration as it was at run time. The deduction is for internal inconsistency — it says retry "is refused here" yet later tells the agent to "and retry to re-run a failed or paused run" with its params, which no `action` enum value supports.

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

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

Front-loaded with the read-only framing and action list, and the dense single paragraph still follows a usable diagnostic order. It loses a point for the retry sentence, which adds length and confusion about an action the schema forbids.

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 return-shape duty and mostly delivers: health's totals/failure rate/blockers, get's ordered step trail, error, retry counts and action_data. What's missing is any sense of list result shape or pagination envelope, and the retry passage muddies which actions are actually callable.

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 every parameter already carries an action-scoped description, so the schema does most of the work; the description's per-action param listings ("params: since, until", "params: type [required], id [required]") restate that mapping. It adds margin insight into when to filter by reason_code or contact_id, but little param 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?

Opens with a specific verb and resource plus an explicit non-effect ("Read executions — this tool changes nothing") and enumerates the three actions (health, list, get). It also names the sibling that owns writes ("Anything that writes (retry) is on `executions_manage`"), so an agent can distinguish this from `executions_manage` without opening either schema.

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

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

Gives an explicit ordered diagnostic playbook (health → scenarios/campaigns `performance` → list → get) with the condition that selects each step, plus concrete branching advice such as filtering by reason_code and calling health first for codes actually occurring. It also states what an empty list-by-contact_id result means, which steers the agent to a different 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?

The annotations already declare this is mutating, non-idempotent, and open-world. The description adds that retry re-runs a failed or paused run and that `step_id` avoids repeating earlier steps, which is helpful behavioral context. It does not explain side effects such as duplicate messages, required permissions, 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?

The definition is front-loaded with the actionable part, but it is overly long and dominated by troubleshooting steps and parameter descriptions for sibling reading actions. Much of that content does not earn its place in a tool that only exposes `retry`.

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 a single action, the description sufficiently explains retry intent and `step_id` usage. However, it does not fully cover retry prerequisites or side effects, and the extensive reading-action context is irrelevant to invoking this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the parameters thoroughly. The description adds retry semantics for `type`, `id`, and `step_id`, but it also details many parameters for health/list/get that are not part of this tool's schema, which can mislead rather than clarify.

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

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

The first sentence is specific: it changes executions and the only available action is retry, with reading actions delegated to the `executions` sibling. However, the subsequent troubleshooting workflow and parameter lists for health/list/get obscure the fact that this tool can only perform `retry`.

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 useful guidance for retrying only after the cause is fixed, and it explicitly separates reading from mutation. But it does not clearly say when to call this tool versus `executions` after the troubleshooting sequence, and it spends most of the guidance on actions this tool cannot perform.

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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is largely pre-supplied; the description's 'this tool changes nothing' mostly restates it. Beyond that it adds pagination context and a note that deleting a folder does not delete its contacts, but that note concerns an action this tool does not offer, so it is dead weight here rather than useful 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?

The first paragraph is tight and front-loaded with scope plus the routing rule. The second paragraph then spends roughly half the definition documenting create/update/delete/add_contacts/remove_contacts, none of which exist in this tool's enum, so those sentences do not earn their place and actively compete with the two real actions.

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-action read tool with a fully documented nested schema and annotations, the description covers the required scope, the sibling boundary, and the action list an agent needs. The only shortfall is that the surplus write-action documentation invites an agent to attempt unsupported actions.

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 already carries an action-tagged description in the schema, so the description adds little new meaning. It restates page/per_page/folder_id without format, default, or limits beyond what the schema already says (default 20, max 100, color enum). Baseline 3 applies when the schema does the heavy lifting.

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

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

The opening sentence names the resource and the two read actions (list, list_contacts) and explicitly names the sibling `folders_manage` that owns every write. That distinguishes it cleanly from siblings. However, the second paragraph reopens with 'Manage contact folders' and enumerates create/update/delete/add_contacts/remove_contacts, which blurs what the tool actually does and is only rescued by the first paragraph.

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

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

It gives an explicit when-to-use and when-not-to-use rule: all writes are on `folders_manage` and are 'refused here'. The alternative tool is named directly, so an agent has no reason to guess.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the safety profile is covered. The description adds real value beyond them by clarifying that deleting a folder leaves its contacts intact and by spelling out which params each action requires, which is the main failure mode for a multi-action tool. It still omits reversibility, permission requirements, and what a create returns.

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

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

The scoping sentence is well front-loaded, but roughly half the text is spent documenting `list` and `list_contacts` — actions this tool's enum does not accept — including their pagination params. That content is both wasteful and actively misleading, and it partially contradicts the opening sentence that reading lives on `folders`.

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 all five mutating actions and their required params, which is the core need for a nested-object multi-action tool. With no output schema, though, the description never indicates what a create or update returns (e.g., the new folder ID), which an agent needs to chain calls. Adequate but with a clear gap.

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

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

Schema description coverage is 100%, so the per-param docs (id, name, color enum, page/per_page defaults and max, folder_id, contact_ids) are already fully documented, including "Not a hex code". The description largely restates the schema's own per-action required mapping rather than adding new meaning. 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?

Opens with a specific verb+resource ("Change folders") and enumerates the five mutating actions, then explicitly names the sibling `folders` as the read path. The only blemish is that the second paragraph re-lists `list` and `list_contacts` as if they were actions of this tool, muddying the otherwise clean split.

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

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

Gives a clear routing rule: mutations here, reading (list, list_contacts) on `folders`. It also warns that delete does not delete contacts, which is the kind of non-obvious consequence that prevents misuse. No guidance on prerequisites or when update vs delete applies, but the read/write split is the decision an agent actually faces.

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 description usefully discloses the prerequisite ordering (fetch this before composing an actions array), which is real behavioral context beyond the annotations. However, the annotation set is internally inconsistent (readOnlyHint=true alongside destructiveHint=true) and the description does nothing to resolve that, nor does it say anything about payload size or cost for a zero-argument call that returns the full enumeration. With read-only semantics already conveyed by "Get", 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?

Two short sentences, zero filler. The purpose comes first and the prerequisite/call-site guidance follows, which is the correct front-loading for a discovery tool.

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

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

For a zero-parameter enumeration tool with no output schema, the description covers the essential contract: what it returns (types, options, branch labels) and when to call it. It stops just short of telling the agent how large or volatile that result is, which matters for a full-catalog fetch.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies an unfiltered full listing, matching the empty input 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 all available action types") and adds what the payload contains ("their options and branch labels"), which lets an agent distinguish it from neighbouring discovery tools like get_trigger_types or get_contact_filter_types.

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 sequencing guidance: "Read this before building the actions array for create_scenario, update_scenario, create_campaign, or update_campaign." It names the four consuming tools, so the when-to-use condition is unambiguous and no sibling comparison 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?

The description adds useful behavior beyond the annotations: it discloses that the result enumerates each type's accepted fields, operators, date ranges, and options, i.e. this is a schema-discovery call whose output drives later construction. Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true); the co-present destructiveHint=true is semantically inert under MCP rules when readOnlyHint is true, so it does not contradict the stated read behavior. The description does not say whether the catalog is static/cacheable or stable across calls, which matters given idempotentHint=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?

Two sentences, both earning their place: the first defines the payload, the second gives the ordering instruction. The prerequisite instruction is front-loaded as the last, most actionable clause, and there is no redundant 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?

With no output schema, the description correctly compensates by naming the contents of each returned filter type, and it explains the one thing an agent must know before calling it (use prior to building the contacts `filter` filters array). Minor gap: it does not describe the container format of the response or whether results can be cached, which for a zero-param catalog tool would have closed the loop entirely.

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 and there is nothing for the description to disambiguate. The description instead describes the shape of the response entries, which is helpful but not required given no inputs exist.

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 plus resource ('Get all available contact filter types') and an enumeration of what each entry contains (fields, operators, date ranges, options). The clause about the contacts `filter` action ties it to a concrete use site, which distinguishes it from the analogous catalog siblings get_action_types and get_trigger_types without the agent 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?

Explicitly states the triggering context: read this before building the filters array for the contacts `filter` action, which tells the agent this is a prerequisite lookup rather than an ad-hoc query. It does not name a when-not condition or an alternative source of the same information, so it stops short of the top mark.

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 are internally inconsistent — readOnlyHint=true alongside destructiveHint=true — and the description does nothing to resolve that, simply framing the call as a plain read. Beyond the "currently authenticated" scope it adds no behavioral context such as caching, permissions required, or rate limits for an openWorldHint=true tool.

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 wasted words. It is efficient, though the efficiency comes partly from under-specification rather than precision.

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 no parameters, the description is the sole source of information about what comes back, and it never says. For a tenant-scoped read whose annotations are self-contradictory, the definition leaves an agent unable to predict the response shape or trust the safety profile.

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 an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; the only useful addition would be clarifying that the organization is inferred from credentials, which is partially implied by "currently authenticated".

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 verb ("Get") and a scope ("the currently authenticated organization"), so the agent knows it is an org-level read, but "information" is left unspecified — there is no indication whether this returns plan, billing, members, IDs, or settings. It does not differentiate itself from near-neighbours like settings or agent, so an agent must guess what payload it yields.

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 any alternative sibling tool. The only implicit signal is the word "currently authenticated," which suggests tenant scoping but not when this call is warranted over settings or agent.

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 this a read-only, open-world fetch, so the description only needs to add context. It adds the useful fact that the response carries option schemas, but says nothing about size, caching, stability across calls, or why the annotations oddly mark a getter as destructive — a notable gap given that mismatch.

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 purpose and followed immediately by the action-triggering instruction. 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 zero-parameter getter with no output schema, the description covers what is returned (trigger types plus their option schemas) and where the result is consumed (the triggers array in create_scenario/update_scenario). A brief note on response shape or ordering would make it complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-parameter tool applies. The description correctly implies no filtering or selection arguments are needed.

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 all available trigger types") and even specifies the payload content ("their options schemas"). It is clearly distinguishable from data-fetching siblings like get_action_types or get_contact_filter_types because it is explicitly scoped to trigger types.

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 prerequisite-style instruction: read this before building the triggers array for create_scenario or update_scenario. That is strong when-to-use guidance. It stops short of a when-not or an explicit alternative (e.g., use get_action_types for action options), so it is not 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?

Beyond the readOnlyHint annotation, it discloses that the data lives on Instagram rather than Inrō, that every action hits the Graph API so the list is always current, that Instagram caps icebreakers at 4, and exactly what the list returns (question, payload, and automations with scenario_id, scenario_title, active, trigger_id, plus the trigger match mode). The 'empty automations array means tapping it starts nothing' note is a genuinely useful semantic detail that no structured field conveys.

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 text is front-loaded well but the description then spends most of its length documenting create/update/delete behavior — payload generation, trigger-breakage on reworded questions, delete params — none of which this tool can perform. That is substantial bloat that also creates confusion about the tool's actual surface.

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 documents the shape of list results including nested automation fields, which is what an agent needs. But roughly half the content describes actions the schema rejects, so the definition is simultaneously over-explained and unclear about whether an agent should ever attempt those actions.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds that list takes no params. It also explains payload as 'as returned by list' and question as the text shown on the profile for the write actions — but those actions are not invocable here, so the extra meaning is only marginally useful for this tool as defined.

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 line is unambiguous — 'Read icebreakers — this tool changes nothing. Actions: list' — a clear verb and resource that also names the sibling handling writes. However, the rest of the description then enumerates create/update/delete with their params, which this tool's schema (action enum: ['list']) does not permit, muddying the otherwise crisp purpose.

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

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

Explicit routing: reads here, and 'Anything that writes (create, update, delete) is on `icebreakers_manage` and is refused here.' That is a direct when/when-not statement naming the alternative. It stops short of saying when an agent should care about icebreakers at all (e.g., before editing a scenario that triggers on one), so it is not quite 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 flag destructive, open-world, and non-idempotent behavior, but the description adds important operational context: the data lives on Instagram via Graph API, the four-item limit, generated payloads on create, and automation side effects when questions change. It also explains that every action returns the full updated list.

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 front-loaded with the action set and then explains each operation efficiently. Some redundancy around `list` and the two separate action enumerations keep it from being fully tight.

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 mutation tool without an output schema, it covers source of truth, limits, side effects, and return shape well. The mismatch between the described `list` action and the schema enum is a notable completeness defect.

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 restates per-action parameter requirements and adds semantic detail such as payload identifying an icebreaker and being generated on create, but it also documents a `list` action whose parameters do not exist 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 and resource: changing icebreaker questions shown on the Instagram profile, and explicitly points reading to the `icebreakers` sibling. However, it later describes a `list` action that the input schema does not permit, which blurs the tool's 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?

Enumerates create, update, and delete with their required parameters, and says reading is on the `icebreakers` sibling, so routing is mostly clear. The embedded `list` guidance conflicts with the enum and creates ambiguity about whether this tool can read.

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 description contradicts the readOnlyHint annotation and the schema enum by detailing create and refresh_upload as if they were actions of this tool. Although it says writes are refused here, the later create/refresh_upload instructions directly conflict with the declared read-only 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?

The description is bloated with detailed create and refresh_upload instructions that do not apply to this read-only tool. The useful read-only guidance is front-loaded, but the majority of the text is irrelevant and confusing.

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 list/get tool, the description covers the actual actions adequately and notes that get returns upload_status. However, the inclusion of extensive write-action details creates ambiguity about what this tool can actually do, reducing completeness despite the schema being fully documented.

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 the actual list/get parameters. The description adds some useful context, such as get returning upload_status for polling, but it also describes create parameters that are not part of this tool's schema.

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

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

The opening sentence clearly states this is a read-only tool with actions list and get, and it names media_files_manage as the sibling for writes. However, the description then spends most of its length explaining create and refresh_upload, which are not valid actions here, muddying the tool's actual purpose.

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

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

It explicitly says writes are refused here and belong on media_files_manage, which is strong routing guidance. It also explains polling get for pending uploads, but the extensive create/refresh_upload guidance is inapplicable and could mislead an agent about when those actions are available.

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 past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing size limits (25MB images/audio, 250MB video), that oversized files are rejected, that the file is stored verbatim while DMs/templates get a smaller derived copy, and that refresh_upload invalidates the old link but preserves already-uploaded parts and reverts failed uploads to pending. It also warns that inline bytes are impossible, closing a likely agent error path.

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 and information-dense, but it is one very long run-on block, and a substantial share of it (list pagination params, get/upload_status polling) describes actions outside the allowed enum, which is noise an agent must filter out. The mode-preference information earns its length; the read-action detail does not.

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

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

There is no output schema, and the description compensates by naming the return fields (upload_url, upload_page_url, expires_at, upload_status) and how to poll them, which is enough to drive the two-phase upload correctly. The remaining gap is the stale list/get documentation that contradicts the action enum and could make an agent attempt an unsupported action.

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 nested properties already carry enum and per-action hints, so the baseline would be 3; the description adds real meaning on top by explaining that media_type is auto-detected in file_url mode but required in the upload_url flow, and by framing file_url explicitly as the lower-context mode. It adds little for id, page and per_page because those belong to actions this tool does not expose.

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?

Opens with a specific verb and resource ("Change media_files") and immediately enumerates the two supported actions, create and refresh_upload, and it routes reads to the sibling `media_files`. It loses a point because the body then documents list and get in detail even though the schema enum only permits create and refresh_upload, blurring what this tool actually does.

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

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

Explicitly orders Mode 1 (file_url, preferred, no context cost) ahead of Mode 2 (upload_url PUT flow) with the condition that selects each, including "any file that only exists locally". It also states when to use refresh_upload rather than creating a new file, and gives the fallback of handing the user upload_page_url and polling media_files:get with backoff.

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, idempotentHint, destructiveHint=false and openWorldHint=false, and the description only echoes that with "changes nothing." The remaining behavioral detail (publish timing, status "published" vs "pending", polling instead of reporting a permalink) describes the write path this tool refuses to execute, so it is largely inapplicable and actively invites misuse of the `get` action as a polling loop. Nothing is said about list pagination behavior, result ordering, or what a read returns.

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

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

The definition is front-loaded correctly, but roughly 80% of its length is devoted to a write workflow (media upload ordering, AI disclosure rules, paid partnership sponsors, trial reels, comment-to-DM automation internals) that this tool's schema cannot execute. That is not conciseness — it is content that belongs on `medias_manage` and that dilutes the two sentences an agent actually 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 carries the burden of explaining return values, and it never says what `list` returns (fields, total count, pagination metadata) or what `get` includes beyond a passing mention of the comment-to-DM automation. Meanwhile it omits nothing about writes because it over-documents them, so the coverage is misallocated rather than balanced.

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 `action`, `id`, `page`, `per_page`, `status` and `search` in detail — the baseline is 3. The description restates the list and get parameter sets without adding meaning beyond them (no syntax for `search`, no note on what `status` filtering does across scheduled vs pending).

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 is excellent: "Read medias — this tool changes nothing. Actions: list, get" names the verb, resource and the sibling (`medias_manage`) that owns writes. But that clarity collapses immediately afterward, where the description spends most of its length explaining create/update/publish/delete semantics for actions that its own schema enum (only `list`, `get`) does not permit, including the instruction "then use create here." An agent reading the body would reasonably attempt an action that cannot be dispatched.

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

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

It gives an explicit negative routing rule — create, update, publish, attach_comment_to_dm and delete "is on `medias_manage` and is refused here" — which is exactly the sibling differentiation an agent needs. What is missing is any guidance on choosing between this tool's two actual actions (list vs get), though the schema's `[list]`/`[get]` tags partially cover that.

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: publish is synchronous, status "published" vs "pending" dictates whether to poll, is_ai_generated and is_paid_partnership can never be added after publish, and agent_context is editable on published posts unlike other fields. The only inaccuracy is the described `list`/`get` actions, which the schema does not accept.

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 action list is front-loaded, which is good, but the action enumeration is repeated twice and the second pass includes invalid actions. Long stretches (AI disclosure, sponsored posts, agent_context) duplicate the schema descriptions almost sentence-for-sentence, so the description is dense rather than efficient.

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, nested-schema tool with no output schema, the description covers the important operational facts: permissions, sync vs async publish, and the response status values plus the advice to report the permalink. The unsupported `list`/`get` actions are the one real completeness defect.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already carries per-parameter meaning including the comment_to_dm sub-object. The description adds cross-parameter relationships (is_paid_partnership pairs with branded_content_sponsors, trial_graduation_strategy is REELS-only, comment_to_dm is create/update-only) but restates several field semantics the schema already documents verbatim.

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?

Opens with a specific verb+resource ("Change medias") and enumerates the five mutating actions, then explicitly routes reads to the sibling `medias` tool. The only blemish is that the body later details `list` and `get` actions with parameters that are absent from the `action` enum, which muddies the boundary the first line establishes.

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 sequencing ("First upload the visual with create_media_file, then use create here"), explicit alternatives ("use this instead of hand-building a scenario", "on an existing post use attach_comment_to_dm"), and explicit exclusions ("Neither is accepted on publish"). It also names the prerequisite permission and points to get_organization_info#can_publish.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: the menu is stored on Instagram and read live from the Graph API, the 5-entry limit, and the idempotent semantics of add 'replaces the entry with the same id in place'. It also explains what ids mean per entry type and that postback payloads reach Inrō as messages while web_url entries reach no automation. Much of the add/update/delete behavior it describes is unreachable from this tool, so not a full 5.

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

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

Front-loading is good — the read-only nature and 'Actions: get' come first. The middle passage then spends several sentences enumerating parameters and side effects for add/update/delete, which are dead weight for invoking this specific tool. Tightening to the get behavior would sharpen it considerably.

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

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

No output schema exists, and the description compensates by stating that get returns each entry's id, type, title, payload, url, and source. Combined with the routing guidance and the entry-id semantics, an agent has enough to call it correctly; only the live-vs-cached distinction and the 5-entry cap leave minor room.

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, and the description largely restates the schema's per-action parameter notes. It does add the useful gloss that 'an entry is addressed by `id`: its payload for a postback, its title for a link' and that the payload is generated when omitted, but these duplicate what the schema already 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?

Opens with a specific verb+resource in 'Read persistent_menu' and immediately names the write sibling `persistent_menu_manage` as the tool for mutations. The following sentences then describe add/update/delete behavior in detail for actions the schema does not permit here, which slightly muddies what this tool actually does. The read scope is still unmistakable, but the noise costs it a point.

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

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

Explicit when-not guidance — 'Anything that writes (add, update, delete) is on `persistent_menu_manage` and is refused here' — plus a named alternative. An agent cannot reasonably route a write to this tool after reading it.

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

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

Goes well beyond the annotations: it explains the menu lives on Instagram rather than Inrō and every action reads back from the Graph API, states the 5-entry ceiling, discloses that the delete/rename of the opt-out entry mutates the opt-out setting, that add replaces an entry with the same id in place, and that each action returns the full updated menu. It also explains the postback-vs-web_url consequence (payload reaches Inrō and can be matched by an icebreaker trigger; web_url reaches no automation) — precisely the kind of side-effect detail destructiveHint/openWorldHint leave opaque.

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

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

Front-loads the key scoping sentence well, but the body is one long run-on paragraph mixing action params, Instagram platform behavior, and automation routing, with a semicolon-heavy final sentence. The redundant mention of a `get` action (already stated as belonging to the sibling) should have been cut and makes the structure actively confusing.

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 nested-object mutation tool with no output schema, it covers return values ('full updated menu'), platform-source-of-truth behavior, entry limits, and side effects on the opt-out setting. The one real hole is the description/schema disagreement over whether `get` is callable here, which an agent could hit as an invalid-enum error.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by tying per-action requirements together ('Required per action — add: title; update/delete: id'), clarifying that `id` is a payload for postbacks but a title for links, and noting payload is generated when omitted and that update preserves position and existing payload. Some of this restates schema descriptions, which caps it below 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?

Opens with a specific verb+resource ('Change persistent_menu') and immediately routes reads to the sibling `persistent_menu` tool, which is exactly the differentiation needed in a catalog full of `*`/`*_manage` pairs. It loses a point because it then lists 'get (no params — returns each entry's id...)' among the actions even though the schema's `action` enum only allows add/update/delete, muddying whether this tool performs reads at all.

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 read path is the sibling `persistent_menu` tool and that this one is for add/update/delete, plus per-action preconditions (title required for add, url required for web_url, id required for update/delete). No explicit 'do not use when' beyond the read split, and the stray 'get' action reference weakens the routing signal.

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, idempotentHint=true, so the description's 'this tool changes nothing' adds little. The genuinely useful item is the priority-vs-normal folder semantics, but it is buried in a block that documents write parameters (action_type, scenario_ids, active) for actions this tool does not expose, which misleads about 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?

More than half the text is a copied block describing manage-only actions, which is dead weight for a tool whose enum is list/get. The signal that matters (read-only, list/get, route writes to scenario_folders_manage) is present but diluted by that noise.

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-action read tool with full schema coverage and annotations, the essential information is covered in the first two sentences. However, the trailing write-action documentation is not merely surplus: it describes behavior this tool does not have, risking mistaken tool selection or malformed calls, so the definition is not complete-and-correct.

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

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

Schema coverage is 100% and the schema already documents id, action_params, enums and per-action requirements. The description repeats those parameter lists without adding format, ID resolution or edge-case detail, so it neither helps nor entirely wastes the slot.

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 sentence is precise: a read-only tool exposing list and get, with writes refused. But the second paragraph then enumerates create/update/delete/duplicate/reorder/toggle_active as if they were actions of this tool, so the description undercuts its own stated scope and leaves an agent unsure whether it can mutate folders here.

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

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

It explicitly names the alternative (scenario_folders_manage) and states that write operations are refused, which is exactly the routing an agent needs. That guidance is then contradicted by the detailed create/delete/reorder action documentation immediately below, which implies those actions are callable on this 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing what is actually destroyed: delete with ungroup keeps scenarios and only unassigns them, while delete_scenarios permanently deletes them. It also reveals that duplicate creates an inactive copy of the folder plus its scenarios and that reorder assigns priority 1 to the first ID — details an agent could not infer from annotations.

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

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

Front-loads actions well, but is repetitive: the action list appears twice and the folder_type semantics are stated twice in slightly different wording. It also spends sentences describing list/get actions that the input schema's enum does not support, which is noise that can mislead.

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 nested, multi-action mutation tool with no output schema, it covers almost everything an agent needs: required params per action, destructive side effects, duplication behavior, and ordering semantics. The one real gap is the internal contradiction about read actions, which could cause an agent to attempt an unsupported action before the schema rejects it.

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

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

Schema description coverage is 100%, so the schema already documents every nested parameter and its per-action applicability, making the description's per-action parameter recap largely redundant. It adds minor value by restating the priority-1 ordering rule for scenario_ids and the create default of `priority`, but nothing substantial 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 opening states a specific verb-plus-resource (manage scenario folders) and enumerates the mutating actions, and the folder_type semantics (priority = only highest-priority matching scenario runs, normal = all run) make the domain purpose concrete. The clarity is undercut by the first sentence claiming reading is on `scenario_folders` while the second block then advertises list/get as actions of this tool.

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?

Strong operational guidance: it routes reads to the sibling `scenario_folders` tool, explains when to choose delete action_type `ungroup` vs `delete_scenarios`, and notes reorder applies to priority folders only. The self-contradictory list/get mention weakens the routing advice, since those actions do not exist in this tool's action enum.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "this tool changes nothing" and enumerates the exact actions that are rejected rather than silently ignored. It goes further by noting the `performance` window is a bounded lookback and that the per-step funnel exposes reason codes, but it omits any note on the cost or latency of the AI/data-heavy `get` path. The only weakness is that much of the text details write semantics the tool cannot perform, which is boundary-setting rather than behavioral detail the agent needs here.

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

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

Front-loading is excellent — the read-only scope and the three valid actions appear in the first sentence. However, the bulk of the middle section is an itemized tour of create/update/trigger/test/delete parameters that this tool will refuse, which is dead weight for a three-action read surface and dilutes the signal the 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?

For a read-only tool with no output schema, the description covers enough: it says `list` is a paginated index with search and folder filtering, `get` returns the full triggers/actions JSON, and `performance` returns a step funnel with reason codes. What's missing is anything about result size or default paging behavior on `get` for large scenarios, which matters given the nested trigger/action tree.

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 per-parameter meaning is already fully documented and 3 is the baseline. The description does add interpretive value for `performance` (per-step funnel, which step is breaking, defaults implied by the schema) and clarifies that `get` returns full triggers/actions JSON plus generation data, but it spends most of its parameter prose on create/update parameters this read-only tool refuses.

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

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

The first sentence delivers a specific verb+resource plus scope: "Read scenarios — this tool changes nothing. Actions: list, get, performance." It then explicitly separates the tool from its nearest sibling by declaring that all write actions live on `scenarios_manage` and are refused here, so an agent can pick correctly without opening any schema.

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

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

Routing is explicit and multi-layered: it names the sibling for writes, tells the agent to call `get_action_types`/`get_trigger_types` before building, points to `executions` for reading the failing runs behind a performance dip, and even flags when to prefer `medias`' `attach_comment_to_dm` over authoring a scenario. When-not-to-use is covered by the "refused here" boundary and the narrow-post 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 flag destructive, non-idempotent and open-world, and the description still adds real substance: update's `actions` is a COMPLETE list where omitted actions are destroyed, trigger replacement rules and the webhook-URL loss on replacement, `test` actually sends messages and is excluded from metrics, and delete permanently removes triggers/actions. The one gap is that `prompt`-based create is described as "async AI generation" without saying how the agent learns the result (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?

Front-loaded and telegraphic, but a large block documents list/get/performance actions that the input schema's enum cannot invoke and that belong to the `scenarios` sibling — duplicated, partly contradictory material in an already dense description. The genuinely high-value warnings are buried mid-paragraph after that block.

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, deeply nested mutation tool with two top-level params and no output schema, it covers build modes, required params per action, and destruction semantics well. It stops short of explaining what create/update return (id? generation status?) or how to poll async prompt generation, which matters 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% and already tags params by action, so the baseline is 3; the description earns an extra point by explaining the semantics the schema states only tersely — the three mutually exclusive create modes, prompt vs triggers/actions exclusivity on update, and the id-presence rule that decides whether triggers are merged or replaced.

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 states a specific verb+resource ("Change scenarios") and enumerates the five mutating actions, then explicitly routes reads to the sibling `scenarios` tool. However, the body then documents list/get/performance parameters in detail even though the `action` enum only permits create/update/trigger/test/delete, which blurs the line the first sentence draws.

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 to call get_action_types and get_trigger_types before building triggers/actions, names a concrete alternative workflow (`medias` → `attach_comment_to_dm`) with the exact conditions that select it (one specific post + DM a link), and scopes this tool to everything wider. It also routes diagnosis to `executions` after reading performance.

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 readOnlyHint=true and openWorldHint=true, so the description's job is to add context beyond that; it does so by scoping the corpus to product documentation and enumerating covered topics. However, it says nothing about retrieval behavior (how many passages come back, whether results are verbatim docs or synthesized, whether sources are cited), and it gives no help reconciling the anomalous destructiveHint=true flag against an obviously non-destructive documentation lookup.

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. The verb and corpus come first, followed by the topic scope, then the imperative usage rule — properly front-loaded and immediately actionable.

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 one required parameter and no output schema, the definition covers what the tool consumes but not what it produces; an agent gets no indication whether to expect doc excerpts, links, or a synthesized answer. For a simple retrieval tool that is a modest rather than fatal gap, but it is the main thing missing.

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

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

Schema description coverage is 100% and the single query parameter already documents that it should be a natural-language question with worked examples. The description's topic list (features, integrations, pricing) mildly reinforces what belongs in a query, but it adds no syntax, length, or phrasing constraints 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 ('Search') and resource ('Inrō product documentation') and enumerates the question domains it covers (features, capabilities, integrations, pricing, how the platform works). It is clearly distinct in subject matter from data-mutation siblings like campaigns_manage or contacts_manage, but it never explicitly names or contrasts with the closest lookup sibling, search_templates.

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

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

Gives an explicit trigger: 'Use this before answering any product-related question.' That is a strong, actionable when-to-use rule. It offers no when-not guidance and names no alternative tool, so an agent facing a borderline query (e.g., a template question that also touches product behavior) has no routing signal between this and search_templates.

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 readOnlyHint=true and openWorldHint=true, and "semantic search" usefully signals fuzzy, relevance-ranked matching rather than exact filtering. However, the description does not reconcile the surprising destructiveHint=true annotation, nor does it describe result volume, ranking, or pagination behavior. Given the annotation coverage the bar is lower, but this is only a partial 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 zero filler; the parenthetical clarification is earned because it resolves an otherwise ambiguous noun.

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 tool is simple (two required params, no nesting, no output schema), so the definition is minimally sufficient to invoke it. It leaves gaps around what a result set contains (template summaries? full bodies?) and how many results come back, which matter for planning a semantic search call.

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

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

Schema coverage is 100%, so the parameters are fully documented in structured fields and the baseline is 3. The description does add real meaning by mapping "templates" to the Scenario/Campaign enum values, which the schema's generic "Type of template to search" does not make explicit, but adds nothing about query syntax or matching 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+resource ("Search for templates") and disambiguates the object of the search by naming the two template kinds, scenarios or campaigns. It stops short of distinguishing itself from siblings like scenarios or campaigns, which list the same entities, but an agent can grasp the tool's scope from the text 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?

It says how the search works (semantic) but never states when to reach for this over the sibling listing tools such as scenarios, campaigns, show_scenario, or show_campaign. No exclusions, prerequisites, or fallback behavior are given, so the agent must infer the routing decision.

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 idempotentHint=true, so the safety profile is covered without the prose; the description's "changes nothing" is reinforcement, not new information. Genuinely additive detail is thin: get returns filters plus a contact count, and list is paginated. The bulk of the behavioral disclosure (contact_filters replaces the whole list, contacts are kept on delete) describes mutations this tool refuses, so it does not help an agent invoke this tool correctly.

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 first paragraph is tight, front-loaded, and earns every sentence. The second paragraph is roughly twice as long and spends most of its words on actions the schema enum excludes, which is wasted space for a two-action read tool. Structure is fine, but the payload is bloated with inapplicable 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 read-only tool with a nested contact_filters object and no output schema, the description should focus on what list and get return and how filtering/pagination behaves. Instead it documents the mutation surface, leaving the agent with no added detail on list response shape beyond "paginated, with filters." The `get_contact_filter_types` pointer is helpful but is framed around building filters, which only matters for the actions this tool refuses.

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 id, page, and per_page including defaults and the max of 100. The description restates those same parameters without adding syntax or format meaning. The remaining parameter discussion covers create/update fields that the action enum does not permit here.

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

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

The opening sentence is precise: "Read segments — this tool changes nothing. Actions: list, get," and it names the sibling that owns writes (`segments_manage`). It also defines what a segment is (saved sets of contact filters that campaigns target), which no schema field conveys. However, the second paragraph then enumerates create/update/delete actions the tool does not expose, muddying an otherwise crisp scope statement.

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

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

Explicit routing is present: writes are refused here and belong to `segments_manage`, and the agent is told to call `get_contact_filter_types` first when building filters. The exclusion is stated up front rather than left to inference. The guidance loses a point because the subsequent create/update/delete parameter coaching applies to an action set this tool rejects, so the agent must self-filter which advice is actionable.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), it discloses real consequence data: delete keeps the contacts, and an update with an empty contact_filters array strips all filters. Those details tell an agent what gets destroyed, which is the main risk with destructiveHint set. It adds little on auth, rate limits, or return values.

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 opening 'Actions: create, update, delete' is front-loaded well, but the second sentence re-enumerates actions including list/get and restates parameters already documented in the schema, creating duplication and internal inconsistency rather than adding 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 destructive, nested-object mutation tool with no output schema, the description covers prerequisites, per-action required params, replace-vs-merge semantics, and delete side effects. It stops short of saying what create/update return (e.g., the segment ID), which an agent would need 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 100%, so the schema already carries parameter meaning and the baseline is 3. The description's per-action parameter notes (id required for update/delete, title required for create, contact_filters replaces the whole list) largely restate the schema, though the replacement semantics are worth surfacing given the destructive hint.

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 resource (segments) and enumerates the mutating operations (create/update/delete), and explicitly routes reading to the sibling `segments`. However, it then re-lists `list` and `get` as if this tool supported them, which conflicts with the schema enum and blurs what the tool actually does.

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

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

It gives a clear alternative ('Reading (list, get) is on `segments`') and a concrete prerequisite ('Call get_contact_filter_types first when building filters'), which is genuine routing guidance. The value is undercut by the misleading claim that this tool supports list/get with page/per_page params.

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, openWorldHint=true, and idempotentHint=false, so the agent knows this is an irreversible outbound write. The description adds the 1000-contact cap and the supported message types, which is useful context, but it does not warn about irreversibility, rate limits, or permission requirements that would matter for a bulk outbound 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 short sentences, front-loaded with the core action and the contact limit. The second sentence largely mirrors the message_type enum, so it is slightly redundant but still compact and readable.

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 11-parameter tool with no required fields and no output schema, the description is adequate but thin: it never explains that at least one of contact_ids/contact_emails/contact_usernames is needed, nor that message_type drives which other fields are required. The schema covers these, but the description does not reinforce the key calling constraint.

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, including the conditional requirements tied to message_type. The description only restates the message-type list and the contact cap, adding 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 states a specific verb and resource ('Send a message to one or more contacts') and enumerates the supported message types, so an agent immediately knows what the tool does. It does not explicitly contrast itself with any sibling, but no sibling in the list is a send tool, so the risk of confusion is low.

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 tool versus alternatives, no mention of prerequisites (e.g., that at least one contact identifier must be supplied), and no exclusions. Usage is only implied by the verb 'send'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description's 'this tool changes nothing' usefully reinforces rather than contradicts that. Beyond that, the rich behavioral content (opt-out status semantics, menu entry side effects, merge vs. replace on `keywords`) all describes `update_optout`, which this tool cannot invoke, so the disclosure is largely inert for the caller.

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 first paragraph is tight and front-loaded, but roughly half the description is a second paragraph devoted to a write action this tool explicitly refuses, including field-by-field guidance and side effects that no caller of this tool can ever trigger. Those sentences do not earn their place and actively risk an agent inferring write capability.

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 some description of what the settings contain is warranted, and the field list gestures at that. However, it frames those fields as update inputs rather than describing what `get_optout` returns, leaving the actual read result under-specified for a tool whose sole action is a 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%, so the schema already documents `action` and every `action_params` field at high fidelity. The narrative restates field meanings (ai_detection, menu_message, keywords replacement semantics) but adds little beyond the schema text, and none of those fields are reachable here since the enum admits only `get_optout`.

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 is excellent: 'Read settings — this tool changes nothing. Actions: get_optout' gives a specific verb, resource, and the single supported action, and names `settings_manage` as the writer. It loses a point because the second paragraph opens with 'Read and update the organization's settings,' which re-blurs the tool's identity after the first sentence had drawn it cleanly.

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 explicitly that writes are refused here and that `update_optout` lives on the sibling `settings_manage`, which is exactly the when-to-use/when-not/alternative triplet. An agent reading only the first two sentences knows which of the two settings tools to 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing downstream effects: contacts gain the `optout` status and are skipped by every automation and campaign, and toggling active adds/removes the Instagram persistent-menu entry. Also discloses partial-update semantics ('only changes what it is given; keywords replaces the whole list'). Missing only operational details like permission requirements 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?

Front-loaded with the key distinction, but two consecutive sentences redundantly restate the tool's scope and action list ('Change settings. Actions: update_optout...' then 'Read and update... Actions: get_optout / update_optout'). The second mention of get_optout is wasted and inconsistent with the schema enum.

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-action mutation tool with a richly documented nested schema and no output schema, this covers effects, merge semantics, and field meaning adequately. The only gap is the internal inconsistency about whether get_optout is callable here.

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

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

Schema coverage is 100%, so the baseline is 3. Much of the field prose repeats the schema descriptions (menu_message, ai_detection), but it does add genuine cross-field meaning: turning active on adds menu_message to the Instagram persistent menu and turning it off removes 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 and resource ('the organization's settings') and names the exact action available (update_optout), plus names the read sibling `settings`. Slightly muddied because the body also lists get_optout as an action even though the schema only permits update_optout.

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 reads to the sibling: 'Reading (get_optout) is on `settings`.' Also states the minimum requirement for the mutation ('takes at least one of them'), which tells the agent how to invoke it. No guidance on when in a workflow to configure opt-out versus other tools, but the when-not case is clear.

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

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

Annotations already declare readOnly/idempotent, and the description adds genuine behavior beyond them: the output is a visual rendering 'as it appears in Inrō' and only a short summary is returned, not the full definition. It does not address the odd destructiveHint=true, which sits uneasily with a pure display operation, leaving one annotation unexplained.

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

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

Three sentences, front-loaded with what is shown, then when to call it, then what is returned; nothing is filler. The first sentence is dense with parentheticals and em-dashes, which slows parsing slightly, but every clause carries information.

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

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

With no output schema, the description steps in to say a short summary is returned and points to campaigns → get for the full definition, which is exactly the missing return-value context. For a one-parameter display tool this covers everything an agent needs to call and interpret 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?

There is a single parameter with 100% schema description coverage ('The ID of the campaign to show'), so the schema already carries the semantics. The description adds nothing about where that ID comes from or how to obtain it, 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 ('Show the user a campaign's flow') and enumerates the exact content rendered: steps, warnings, included/excluded folders and segments, and recipient count. It also explicitly distinguishes itself from the sibling 'campaigns → get', so an agent can differentiate 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 triggers: call it after campaigns_manage create/update so the user can verify what will be sent and to whom, or when the user asks to see a campaign. It names the alternative (campaigns → get for the full definition), which is precisely the routing information 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?

Beyond the annotations, the description discloses that this produces a user-visible rendering of the flow and returns only a short summary, plus where the complete data lives. That is real context the annotations do not carry. It does not, however, explain the surprising destructiveHint=true on an ostensibly display-only operation, leaving one behavioral oddity unaddressed.

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, both load-bearing: the first defines the output, the second handles timing and the alternative. The visual purpose is front-loaded and there is 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?

For a one-parameter display tool with no output schema, this covers purpose, timing, return shape, and the sibling alternative. The only residual gap is the unexplained destructive-oriented annotation, which an agent might want clarified before invoking a UI action.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines 'id'. The description adds only that the object being shown is a scenario — no format, sourcing, or lookup details beyond that. Baseline 3 applies 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 verb and resource ('Show the user a scenario's flow') and enumerates what is displayed — trigger, steps, branches, warnings — as rendered in Inrō. It also explicitly separates itself from 'scenarios → get' for the full definition and from 'scenarios_manage' for writes, so an agent can pick correctly without opening another 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 two concrete trigger conditions: after creating/updating a custom scenario with scenarios_manage, or when the user asks to see one. It also names the alternative for a different need (full definition via scenarios → get), which is exactly the when-versus-when-not routing 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 declare readOnlyHint=true, but the description says 'Read and publish' and describes create/update/publish/delete actions, contradicting the read-only annotation. Although it also says writes are refused, the mixed signals make the behavioral profile inconsistent.

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 long and includes a large block about write actions that are not in the action enum, plus repeated warnings. It is not front-loaded cleanly because the read-only claim is immediately followed by contradictory write instructions.

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-action read tool, the description covers list/get parameters and pagination, but the extensive write-action content is irrelevant and misleading. The internal inconsistency leaves the agent less certain about the tool's actual capabilities.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds some meaning for agent_context and is_ai_generated, but those parameters belong to unavailable write actions; for the actual list/get actions it mostly restates schema tags.

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 sentence states a read-only scope and names list/get, and it distinguishes the tool from stories_manage. However, the next paragraph says 'Read and publish Instagram stories' and details create/update/publish/delete, so the tool's actual purpose is contradictory and unclear.

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 explicitly routes writes to stories_manage, but then instructs 'use create here' and gives create/publish workflows that are impossible under the list/get enum. The when-to-use guidance is therefore unreliable and misleading.

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 carry destructive/openWorld/idempotent hints, and the description layers on genuinely new behavior: publishing blocks until live so no polling is needed, only status 'pending' requires polling get until 'published' or publish_status 'ERROR', and is_ai_generated is applied at publish time and can never be added afterwards. It also explains that agent_context is never shown on Instagram and can be changed on published stories, unlike other 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 operational advice is front-loaded and useful, but the middle section enumerates every action and its params, duplicating the schema verbatim, and the list/get discussion contradicts the declared action set. Tightening to the non-obvious constraints would remove real waste and the internal inconsistency.

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 multi-action tool with no output schema, the description covers prerequisites, permission requirements, publish-wait semantics, and failure states ('ERROR'). The one material gap is that it never reconciles its documented action set with the schema enum, leaving an agent unsure whether to filter by status via this tool or via `stories`.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still adds meaning: the create_media_file predecessor for media_file_id, the ordering constraint on is_ai_generated, and the distinction between agent_context and normal story content. It partly repeats parameter enumerations already in the schema, which limits the gain.

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 line states a specific verb and resource ('Change stories. Actions: create, update, publish, delete') and correctly routes reads to the sibling `stories`. That clarity is then undercut by the second paragraph, which goes on to document list/get actions the schema's enum does not accept, muddling what the tool actually does.

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

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

Strong routing guidance: it names the read sibling, gives the prerequisite 'First upload the visual with create_media_file, then use create here', and points at get_organization_info#can_publish for the publishing permission. The list/get documentation introduces a false alternative path, but the when-to-use context for the mutating actions is explicit.

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