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

Annotations already declare non-read-only, destructive, non-idempotent, and open-world behavior, so the bar is lower. The description still adds genuine context beyond them: the implicit draft-publish side effect and the specific plan-limit failure mode (403 plan_limit_reached), both of which affect an agent's decision to call it.

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

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

Four short sentences, front-loaded with the action and effect, then side effects, then failure mode. Every sentence carries information, though the body instruction could be folded in more cleanly rather than placed last.

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

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

For a one-parameter tool with no output schema and rich annotations, the description covers effect, side effect, and the main error condition. It could be stronger by stating what happens when the flow is already live (relevant since idempotentHint is false) and by routing to publish_flow versus this tool.

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

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

Schema coverage is 100% with a single required integer id, so the schema carries parameter meaning. The description's "Send {} as the body" adds a small structural hint but is slightly ambiguous alongside a required id property, and it doesn't clarify where the id is supplied.

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 ("Activate a flow. Sets the flow live") and adds the key mechanism that the draft is published first. It does not explicitly contrast itself with the closely related publish_flow and pause_flow siblings, so an agent must infer the boundary between "activate" and "publish".

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

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

Usage is implied by the effect (making a flow live, mirroring the builder's toggle), which gives the agent a clear mental model. There is no explicit when-not guidance or named alternative among publish_flow, pause_flow, or update_flow, which is a real gap given several overlapping 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?

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses the key side effect — the first snapshot is taken immediately — and enumerates three distinct error outcomes with their conditions (invalid_param, plan_limit_reached, conflict on already-tracked accounts). That is exactly the mutation context an agent needs before committing.

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

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

Four compact sentences, front-loaded with purpose followed by preconditions and error semantics. No repetition of the title, no filler, and each sentence carries actionable 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 one-parameter mutation with no output schema, the description covers purpose, mechanism, preconditions, side effects, and all known failure modes. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% with a single parameter, so the schema already documents the handle format, the @ prefix tolerance, and the public-business-account requirement. The description reinforces the account-type constraint but adds no new syntax or formatting detail beyond what is structured. 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 ('Track a competitor'), plus the mechanism ('Looks the handle up through Meta and starts tracking it'). This clearly separates it from siblings like list_competitors, get_competitor, and remove_competitor without requiring the agent 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?

Gives explicit preconditions and exclusions: the account must be a public Instagram business or creator account, and personal/private accounts cannot be read. It also maps failure modes (422, 403, 409) to causes, which tells the agent when the call will fail. It stops short of naming alternative tools for listing or removing competitors, so 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?

Goes well beyond the annotations: discloses the public posting side effect, that the AI draft is retained and an 'edited' flag becomes true, the 409 not_pending failure mode, and that success consumes the plan's reply cap. It even documents the transport requirement (Content-Type: application/json, empty object instead of a bodiless POST), which is exactly the kind of operational detail annotations cannot express.

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 action and effect, then layers edit semantics, failure mode, quota, and transport requirements in a tight block with no filler. It is dense but every sentence carries operational value; only the transport note could arguably be tightened.

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, non-idempotent mutation with annotations covering the safety profile, the description supplies preconditions, side effects, and quota impact. The one remaining gap is the response shape — no output schema exists, and 'edited becomes true' hints at a return field that is never described.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: 'text' replaces the AI draft rather than appending to it, the draft survives, and an 'edited' flag flips — semantics not conveyed by the schema's one-line 'Post this instead of the AI draft.'

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 ("Approve a reply") and immediately describes the effect: it posts the pending reply publicly under the comment as the account. This is distinguishable at a glance from reject_comment_reply and the bulk variants in the sibling list.

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

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

Gives a concrete precondition for use — only a pending comment can be approved, otherwise 409 not_pending — and explains the two invocation modes (approve the AI draft vs. post edited text). It does not explicitly route to reject_comment_reply or the bulk tools, so alternative selection is left implicit.

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 a non-read-only, non-idempotent mutation, and the description adds real context beyond that: it discloses the status transition (pending or escalated to active) and the transcript side effect of a system line. It still omits permission requirements and any notification side effects.

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

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

Three short sentences with the purpose front-loaded and the two body variants stated compactly. The inline JSON notation is slightly dense but earns its place by disambiguating assign versus unassign.

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

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

For a two-parameter mutation with no output schema, the description covers the action, the payload variants, and the resulting state and transcript effects. Only permission/auth expectations and whether the caller is notified are missing.

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

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

Schema coverage is 100% and already documents both id and assigned_to including the null-to-unassign case, so the description largely restates the schema. It confirms the body shape but adds no format or constraint details 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?

States a specific verb pair and resource ('Assign or unassign a conversation') and covers both directions in one tool. It does not name a sibling such as update_conversation to distinguish scope, so it stops short of a 5.

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

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

The body examples implicitly tell the agent how to choose assign versus unassign, and the note that it moves pending/escalated conversations to active hints at applicable states. There is no explicit guidance on when to use this instead of update_conversation or other conversation tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description's value-add is the behavior it does disclose: blocking works via handle even before the user has messaged, and via conversation_id the block applies cross-channel. It does not state whether the block is reversible via unblock_user, whether an unknown handle errors or creates a stub, or what is returned.

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

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

Two sentences, front-loaded with the action and then the input rule, with no filler or redundancy.

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

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

For a two-parameter mutation with no output schema, the description covers the action, both inputs, and the exactly-one constraint. It leaves gaps only on edge behavior (neither/both supplied, unknown handle, reversibility) that are minor for this tool's complexity.

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

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

Schema coverage is only 50% because conversation_id is undocumented, and the description compensates by defining it as the person behind an existing conversation on any Meta channel. It also adds the mutual-exclusivity constraint (exactly one of the two), which appears nowhere in the schema (no required fields, no oneOf).

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 ("Block a user") and enumerates the two identification modes, so the agent knows exactly what the tool does and which inputs select which mode. The operation is clearly distinct from siblings like unblock_user and list_blocked_users without naming them.

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

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

"Send exactly one of ig_username ... or conversation_id" gives explicit routing guidance between the two input paths, which is more than an implied usage. It stops short of naming alternatives (e.g., list_blocked_users to check state, or unblock_user) or stating when blocking is the right action versus muting/handling.

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

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

Beyond the annotations it discloses the failure contract (422 missing_fields, 409 slot_unavailable), the immediate-confirmation semantics, downstream syncs to Google Calendar and GoHighLevel, and the appointment.booked event. It also explains the side effect of the confirmation DM, which is exactly the kind of behavior annotations cannot convey.

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

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

Front-loaded with the action, then layered with validation, side effects, and parameter notes in a compact paragraph. It is dense but nearly every clause carries information; the nested parenthetical error codes are slightly heavy for prose but earn their place.

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

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

For a 12-parameter mutation with no output schema, the description covers outcomes, error states, and side effects well enough to call the tool safely. The remaining gap is the handful of optional fields (cost, notes, location, vehicle_info) that neither schema nor description explains.

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

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

With 58% schema coverage, the description compensates well for the most consequential params: conversation_id's channel/DM effect, timezone defaulting to account timezone, wall-clock semantics of date/time, service_type sourcing from booking.bookable_services, and duration fallbacks. It leaves cost, notes, location, vehicle_info, and the customer sub-object undocumented, so the coverage is strong but not complete.

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

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

The description opens with a specific verb and resource ("Book an appointment") and immediately qualifies how the booking behaves. It is clearly distinct from siblings like reschedule_appointment or cancel_appointment, but it never names those siblings or get_availability to draw the line explicitly.

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

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

It gives concrete usage context: attach conversation_id when booking for a person in an active chat, and confirmation DM is controlled by send_confirmation. What's missing is guidance on the surrounding workflow (e.g. call get_availability first, or use reschedule_appointment to move an existing booking).

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

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

Annotations already declare destructive, openWorld, and non-idempotent, but the description adds substantive detail beyond them: the draft content is sent on the agent's behalf, each approved reply becomes a public post under the comment, and partial failures are reported per id with a reason. The only gap is that reversibility/undo after public posting is not stated.

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

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

Five short sentences with no filler: action first, then mechanics, then failure semantics, then the limit, then the side effect, then the confirmation requirement. Every clause conveys an operational constraint an agent needs.

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

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

For a single-parameter, no-output-schema mutation tool this covers action, limits, partial-failure reporting, and the public side effect — enough to call it correctly. It leaves out whether a posted reply can be retracted and what the success payload looks like, which matters somewhat given destructive=true and 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 0%, so the description carries the burden, and it does: ids must reference pending replies, are processed in the given order, exceed-100 is disallowed, and non-pending ids land in the failed set. It never states whether an id from a different account/workspace is rejected, but the meaningful semantics are covered.

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 ("Bulk approve replies") plus the mechanism ("Sends the AI draft for each pending id"), which is far more informative than the name alone. It implicitly contrasts with the single-item approve_comment_reply sibling via "bulk" and "each pending id," but never names the sibling explicitly, so an agent must infer the routing.

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

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

Gives clear operating context: only pending ids are actionable, the cap is 100 per call, and it explicitly requires user confirmation before invocation. It stops short of naming alternatives such as approve_comment_reply for a single id or bulk_reject_comment_replies, so the when-not-to-use case is only implied.

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

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

With annotations already covering safety profile, the description adds genuine behavioral detail: it states exactly what happens per id ('Drops the pending draft'), how non-qualifying ids are treated, and names the response field 'rejected'. Minor tension worth noting: the ignore-if-not-pending behavior reads as effectively idempotent, while idempotentHint is false, and dropping a draft is a deletion-like effect despite destructiveHint=false — enough to warrant caution but not a direct contradiction.

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

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

Three short sentences, front-loaded with the action, then the effect, then the no-op case and return field. Nothing is redundant or padded.

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

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

There is no output schema, and the description usefully names the 'rejected' count field, so an agent can anticipate the shape of a result. However, it omits the 100-id cap, permission requirements, and whether a rejected draft can be recovered — gaps for a mutation tool with 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 0%, so the description must carry the meaning, and it does explain that ids refer to replies and that non-pending ones are silently ignored. It does not disclose that ids is an array of 1–100 integers, the per-call cap, or what counts as a valid reply id, so compensation is partial.

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

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

The description names a specific verb and resource ('Bulk reject replies') and, together with the `ids` array, makes the batch scope unambiguous against single-item siblings like reject_comment_reply. It stops short of explicitly contrasting itself with reject_comment_reply or bulk_approve_comment_replies, so the differentiation comes mostly from the tool name rather than the prose.

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?

'Ids that are not pending are ignored' conveys a real precondition (only pending drafts can be rejected) and implicitly tells the agent this is a no-op tolerant operation. There is no explicit when-to-use routing to reject_comment_reply for a single id, no note on batch limits, and no mention of required approvals/permissions.

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 by disclosing the side effects: status becomes cancelled, Google Calendar and GoHighLevel events are removed, and appointment.cancelled is fired. It also names the 409 already_cancelled failure mode, which is exactly the state an agent needs before retrying. Minor gaps remain: no statement about irreversibility, whether the contact is notified, or what a 404-style missing-id case 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?

Four short telegraphic sentences, side effects front-loaded and the error contract placed before the body instruction. Nothing is wasted.

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

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

For a destructive single-parameter mutation with no output schema, the description covers side effects, downstream integrations, the emitted event, and the key error case. It stops short of documenting auth requirements and post-cancellation response shape, but an agent has enough to call it correctly.

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

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

Schema coverage is 100% and there is only one documented parameter, so the schema already carries the meaning. The added instruction "Send {} as the body" is mildly ambiguous alongside a required id and adds little beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Cancel an appointment") and immediately scopes what cancelling means operationally, so an agent can distinguish it from siblings like update_appointment, reschedule_appointment, or book_appointment without opening a schema.

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

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

Implies when to use it (the appointment should not already be cancelled, since 409 already_cancelled is returned), but there is no explicit guidance on when to prefer cancel over reschedule_appointment or update_appointment, and no mention of prerequisites such as permissions.

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

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

Annotations only flag it as destructive, open-world, and non-idempotent; the description adds real substance beyond that: the trigger goes live immediately, is saved paused rather than refused when the live-trigger cap is hit (signalled via created_paused), and a paused trigger stays paused through edits until active: true is sent. It also discloses that creation starts DMing real commenters and that draft mode skips template/button requirements. That is exactly the kind of lifecycle and consequence disclosure annotations cannot carry.

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 content is useful but the prose is repetitive and loosely ordered: 'Creates a trigger.' duplicates the first sentence, 'It goes live at once' appears twice in different paragraphs, and the confirm-with-the-user/draft choice is restated near the end. The most consequential fact (goes live immediately and DMs real commenters) is not front-loaded, which weakens scanability for an agent deciding whether to call it.

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 19-parameter creation tool with no output schema, the description covers the critical operational facts: live-vs-paused behavior, the cap fallback, draft mode, and the button option. Remaining gaps (the post_id vs post_url distinction, response_mode interactions) are handled by the schema, so nothing essential is missing, though the pricing/plan gating on tag_id is left entirely to the schema.

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

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

Schema description coverage is 89%, so the schema already documents nearly every parameter, and much of the description's parameter talk (buttons optional up to three, draft skips requirements) merely echoes it. The one genuine value-add is the rationale that a reply button's tap opens the conversation so follow-ups can be sent, which helps the agent choose button types. Baseline 3 is appropriate given how thoroughly the schema already explains 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 states a specific verb and resource (create a comment trigger), which cleanly separates it from list_comment_triggers, update_comment_trigger, and simulate_comment siblings. The immediately following 'Creates a trigger.' is a pure restatement that adds nothing, but the core identification is unambiguous.

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

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

Strong when-to guidance: it says to confirm with the user first because creation starts DMing real commenters, and it explains the draft: true escape hatch for saving an incomplete trigger paused. It also explains when story/live source types are relevant (Instagram-only, never post-scoped). It does not route the agent between this tool and update_comment_trigger or duplicate_comment_trigger, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write-ness is covered. The description adds genuinely new behavioral facts: field_key is immutable after creation and the account is capped at 15 active fields. It stops short of describing what happens on a duplicate key or what the call 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?

Three short sentences, front-loaded with the action, then the two constraints an agent most needs before committing. No filler or restated schema 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?

For a simple three-parameter creation tool with annotations covering the safety profile, the core facts are present. Missing pieces are failure behavior on duplicate field_key, whether creation is scoped to the current account, and any return value, which matter because there is no output schema.

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

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

Schema description coverage is 0%, so the description carries the burden; it meaningfully explains field_key (permanent, so choose carefully) but says nothing about label or how the type enum values affect behavior. With one of three parameters enriched beyond the schema, the compensation is partial.

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?

"Create a custom field" states a specific verb and resource, and the body clarifies what a custom field's key semantics are. It does not, however, position itself against siblings like update_custom_field or list_custom_fields, so an agent must infer the create-vs-update distinction from the name 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?

The 'Up to 15 active fields' clause gives an implied precondition that an agent can check before calling, but there is no explicit when-to-use vs. when-not guidance and no mention of the update_custom_field alternative for existing fields. Usage context is inferable rather than stated.

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

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

Annotations already establish non-readonly, non-destructive, non-idempotent behavior, so the description's job is to add context beyond that. It does so meaningfully: it warns about plan-cap consumption and discloses that embedding occurs immediately with a possible embedding_pending lag state, which is real behavioral information an agent cannot get from annotations. It does not describe what happens on cap exhaustion or how duplicates are handled.

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

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

Three short sentences, front-loaded with the action, then the cost warning, then the return-state note. No filler words; each sentence carries a distinct piece of 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 does well to name the embedding_pending response field, which an agent would otherwise not anticipate. However, for a five-parameter creation tool at 20% schema coverage, leaving four parameters and all failure modes unexplained leaves the definition only partially 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 only 20% — only the keywords parameter carries a description — so the description is expected to compensate. It does not: question, answer, active, and category_id receive no explanation of meaning, defaults, or constraints, and "The answer is embedded" is the only hint about answer 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?

"Create an FAQ" states a specific verb plus resource, which cleanly separates it from list_faqs, update_faq, get_faq and delete_faq in the sibling set. It does not explicitly name those siblings, so differentiation is implicit rather than stated.

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

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

The description never says when to reach for this tool versus update_faq (for existing entries) or create_custom_field-style alternatives, nor does it state prerequisites. The only contextual signal is the plan-cap warning, which constrains use without guiding selection.

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

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

With annotations already declaring non-read-only, non-destructive, non-idempotent, the description adds real behavior: upfront validation across structure, per-node config, node cap, channel compatibility and keyword collisions, with a 422 invalid_definition response carrying errors[] and warnings[]. The draft-only state and the layout side effect on first open are disclosed. It doesn't say whether a failed validation leaves any partial object behind.

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 action and the draft outcome, then the validation detail, then the lifecycle note. Dense but every sentence carries information; the final sentence about the visual builder layout is the least essential and could be trimmed.

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 deeply nested tool with four parameters, nested definition graph, and no output schema, the description covers the creation semantics, the validation surface, the failure signal, and the downstream lifecycle. An agent has enough to call it correctly and interpret a 422.

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 75%, so the schema carries most field-level meaning, but the description adds a layer the schema cannot express: which aspects of `definition` and `channels` are actually validated (per-node config, channel/trigger compatibility, cross-flow and custom-field references). Individual params like name and tag_id get no added meaning, which keeps it off a 5.

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

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

States a specific verb and resource ("Create a flow") and immediately narrows the effect to "Creates a DRAFT from a definition", which separates it from publish_flow/activate_flow and update_flow. The reference to GET /flows/nodes tells the agent where the definition schema comes from.

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?

Clear context: use this to create a draft, and nothing runs until publish and activate. It doesn't explicitly route to validate_flow for pre-checks or to update_flow for changing an existing flow, nor does it state when not to use it, so it stops short of full when/when-not guidance.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false) the description discloses non-obvious behavior an agent could not guess: a plain draft never consumes a plan slot while scheduled/published posts do, TikTok-only posts reject carousel/story and carry no first comment, and a scheduled-post auto-reply without a free live-trigger slot fails with 403 plan_limit_reached. The timezone interpretation of a bare local time and the paused-save behavior for triggers are exactly the kind of consequences annotations cannot convey.

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

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

Purpose and draft-vs-scheduled behavior are front-loaded, then media flow, then a compact "Rules:" block of exceptions. The prose is dense and the TikTok/comment-trigger rule sentences are long, but each clause encodes a real constraint rather than filler.

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

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

For a 10-parameter tool with a nested tiktok and comment_auto_reply object, no output schema, and plan-tier gating, the description covers the failure modes and side effects well. The remaining gap is that with zero required parameters it never states the minimum needed to create anything meaningful, nor what the create response returns for the subsequent media upload step.

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

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

Schema coverage is 80%, so the baseline would be 3, but the description adds real meaning on top: scheduled_at accepts ISO-8601 with offset and a bare local time is resolved against the account timezone, and tiktok.privacy_level is constrained to the creator's live options from a sibling endpoint. It does not, however, add anything for platform, post_type, hashtags or caption beyond what the schema already says.

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

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

The description opens with a specific verb and resource ("Create a post") and immediately narrows the outcome type: a draft by default, a scheduled post when scheduled_at is set. That distinction separates it in spirit from schedule_post/publish_post/update_post, though those siblings are never named, so an agent must infer the boundary rather than read it.

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 operational sequence (create, then POST /posts/{id}/media, then publish or schedule) and states concrete preconditions: scheduling requires a caption and a future time, TikTok privacy_level must come from GET /posts/capabilities. What's missing is explicit when-not guidance or a named alternative tool for the cases this tool refuses (e.g., where to go for an existing-post edit).

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description discloses two behaviors an agent cannot infer from structured fields: the call consumes plan quota, and is_virtual is silently coerced to false when Google Calendar/Meet conditions are not met. The coercion is the standout detail. It stops short of saying what is returned or whether creation fails on hitting the plan cap.

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

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

Three short, front-loaded sentences with no filler; the core action leads and the caveats follow. The telegraphic phrasing ('Meet links are on') is slightly compressed but still parseable.

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 mutation with 10 parameters, low schema coverage and no output schema, the description covers the trickiest parameter and the quota side effect but leaves the price/duration/display_order semantics undefined. An agent would need to guess how price interacts with price_unit before calling.

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

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

Schema description coverage is only 20% across 10 parameters, so the description is expected to compensate and largely does not. The is_virtual explanation repeats the schema's own description almost verbatim, while price_unit's enum semantics (fixed vs hourly vs per_unit vs quote), duration_minutes, display_order, category_id and active receive no explanation at all. Only the image-exclusion note adds genuine beyond-schema meaning.

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

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

States a specific verb and resource ('Create a service'), which an agent can immediately place alongside list_services, get_service, update_service and delete_service. It does not explicitly name those siblings to differentiate, but the create/read/update/delete naming makes the split unambiguous.

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

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

'Counts against the plan cap' flags a real precondition (quota consumption) an agent should weigh before calling, and the create-vs-update distinction is implied by the name. However, there is no explicit when-to-use/when-not guidance and no pointer to update_service for modifying an existing record.

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 states "Idempotent on name", but the annotations declare idempotentHint=false. That is a direct conflict about whether a repeated call has additional effect, which is exactly the question an agent needs answered before retrying. The status-code detail (201 vs 200) and the colour-unchanged rule are genuinely valuable, but they are undermined by contradicting the structured metadata.

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

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

Two short sentences, zero filler, with the operation stated first and the idempotency/status-code behaviour immediately after. Nothing needs trimming.

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 two-parameter create tool with no output schema, the description usefully explains both return paths (201/200), which is what an agent needs to interpret a result. However, the idempotency conflict with annotations leaves the retry-safety question ambiguous, and nothing is said about permissions or what the returned tag looks like.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does add real semantics: name is the identity key for idempotency, and colour is only applied on first creation ("colour unchanged" on the 200 path). It still omits the colour format/default (#5046E5, hex pattern) and the name length bounds, so it only partially compensates.

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

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

The description opens with a specific verb and resource ("Create a tag"), which unambiguously separates it from the sibling read/delete/link operations (list_tags, delete_tag, tag_contact). An agent can identify the operation without opening the schema.

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

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

Usage is only implied: the tool is the way to mint a tag before it can be attached via tag_contact. There is no explicit when-to-use/when-not, no statement about prerequisites (e.g. whether the tag must not already exist), and no named alternative for the 'tag already exists' case.

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 substantial behavior beyond the annotations: the trigger stops firing, disappears from lists, retains stats, and causes linked flows to be detached and paused. It also notes that a detached_flows count is returned, which is useful operational context for a destructive action.

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

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

The description is concise and front-loaded, with the core action stated first and the important soft-delete consequences following immediately. Every clause adds useful information without redundant wording.

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

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

For a simple one-parameter delete operation with full schema coverage and no output schema, the description is complete enough. It explains the non-obvious soft-delete effects and the detached_flows result, which are the main details an agent would need before invocation.

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

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

The input schema has 100% description coverage and documents the single required id parameter as a numeric id. The description does not add further meaning about the id, but the schema already covers the parameter adequately.

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: deleting a comment trigger. It also clarifies that this is a soft delete, which distinguishes the operation from merely updating or pausing a trigger.

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

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

Usage is implied by the verb 'Delete' and the soft-delete consequences, but the description does not explicitly say when to use this tool instead of alternatives such as updating or pausing a trigger. There are no exclusions or named sibling alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds one genuinely useful piece of context beyond that: the document's embeddings are deleted as well, a cascade effect the annotations do not express. It stops short of stating irreversibility, permission requirements, or behavior when the id does not exist.

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

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

Two short sentences, front-loaded with the action and with zero filler. The second sentence earns its place by adding the embedding cascade, though "Removes the document" slightly restates the first sentence.

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

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

For a simple single-parameter mutation with rich annotations and no output schema, the description is barely adequate. It omits irreversibility, error behavior for unknown ids, and side effects on anything referencing the document, which matter for a destructive operation.

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

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

Schema description coverage is 100% with a single required integer, so baseline is 3. The description adds nothing beyond the schema and does not clarify that the id is the document id returned by list_documents or get_document, leaving the identifier's origin implicit.

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 ("Delete a document") plus a scope detail, so the agent knows exactly what is removed. The resource is unique among siblings (delete_flow, delete_post, delete_tag target other entities), so no explicit sibling differentiation is needed, though none is offered.

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 mention of prerequisites or permissions, and no statement about alternatives (e.g., update_document or archiving instead). The agent must infer context entirely from the tool name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description earns credit for disclosing something annotations cannot express: that the FAQ's embeddings are deleted along with the record, a cascading effect an agent should know before calling. It stops short of saying what happens with a nonexistent id.

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

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

Two short sentences with zero filler, and the primary action is front-loaded ahead of the side-effect detail. Nothing redundant is included.

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

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

For a single-parameter destructive tool with full annotation coverage and no output schema, the description supplies what matters most: the action and the non-obvious cascade to embeddings. It could add error behavior for missing or already-deleted ids, but overall it is adequate for the tool's simplicity.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema fully documents 'id' as a numeric id. The description adds nothing about the parameter, which matches the baseline 3 for high-coverage schemas.

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

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

The description names a specific verb and resource ('Delete an FAQ') and adds the side effect that the FAQ's embeddings are removed too, which distinguishes it from siblings like update_faq or get_faq. It doesn't explicitly contrast itself with those siblings, but the verb-resource pairing is unambiguous.

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

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

There is no guidance on when to use this versus alternatives such as update_faq (for retiring content without deletion) or get_faq, and no stated prerequisites or warnings. The agent must infer usage entirely from the name.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description goes further by disclosing exactly what is destroyed (versions, sessions, media, analytics), the side effect on a linked comment trigger (detached and paused), and the irreversibility of the operation.

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

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

Front-loaded with the action and its consequences, then the safety guidance. Slight redundancy between 'Delete a flow' and 'Deletes the flow, its versions...' but every clause carries distinct 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 single-parameter destructive tool with no output schema, the description covers scope, side effects, permanence, and the safer alternative — nothing an agent needs to call it responsibly is missing.

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

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

Only one parameter ('id') and schema coverage is 100%, so the schema fully documents it. The description adds no format or sourcing detail for the id, which is acceptable at this coverage level but earns only the baseline.

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 ('Delete a flow') and immediately enumerates the cascade scope (versions, sessions, media), which distinguishes it from siblings like pause_flow or discard_flow_draft.

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

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

Explicitly names the preferred alternative ('prefer pause_flow') and adds a procedural guardrail ('Confirm with the user'), so the agent knows both the safer path and the required confirmation step.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing cascading effects (media files are removed), the specific failure mode and error code for published posts, and the resulting external state (the live post remains on the platform). It does not address reversibility or required permissions, which keeps it off a 5.

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

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

Three short sentences, front-loaded with the action, then effects, then the blocking condition and its consequence. No filler and no repetition of annotation content.

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

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

For a destructive single-parameter mutation with no output schema, the description covers the essential behavior: what gets removed, what fails, and what happens to the external resource. Reversibility and permission prerequisites are the only notable omissions.

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

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

With a single required parameter at 100% schema description coverage, the schema already tells the agent everything about the `id` field. The description adds no additional meaning about the identifier, such as where to obtain it or whether it refers to an internal post id versus a platform-side id, so it lands at the baseline.

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?

"Delete a post" names a specific verb and resource, and the following sentences define the exact scope of deletion (post plus media files) and its limiting condition. An agent can distinguish this from siblings like update_post, unschedule_post, or publish_post 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?

It gives an explicit when-not-to-use rule: published posts cannot be deleted and will surface a 409 not_editable. It stops short of naming the alternative action an agent should take instead (e.g., unschedule or check status first), so the routing guidance is clear but not complete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations by specifying that embeddings and the image file are also removed, which is important cascade information for an agent.

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

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

The description is two short sentences, front-loaded with the action and followed by the key side effects. Every sentence carries useful information with no wasted wording.

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

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

For a simple one-parameter destructive tool with rich annotations and full schema coverage, the description provides enough context to call it safely, especially the cascade effects. It could say more about irreversibility or downstream impact, but the essential information is present.

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

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

Schema description coverage is 100%, and the single id parameter is documented as "Numeric id." The description adds no additional parameter meaning, so the baseline of 3 is appropriate when the schema does the work.

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

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

The description uses a specific verb and resource: "Delete a service." It is immediately distinguishable from sibling deletion tools such as delete_flow, delete_faq, and delete_document because the resource is explicitly named.

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

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

The description states what the tool does but gives no explicit guidance on when to use it versus alternatives such as update_service or get_service. Usage is only implied by the verb "Delete," with no exclusions or prerequisite context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description earns credit for disclosing exactly what is destroyed and the cascade effect on contacts and conversations, which annotations cannot express. It stops short of stating irreversibility or behavior when the id does not exist.

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

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

Two sentences, front-loaded with the operation and followed by the consequence. Every clause carries information an agent needs; nothing is padding.

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

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

For a one-parameter destructive tool with annotations and no output schema, the definition covers what an agent must know: what is deleted and the blast radius. A line on irreversibility or on the error case for an unknown id 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?

There is a single required parameter with 100% schema coverage, though the schema text ("Numeric id.") is uninformative about which object the id belongs to. The description adds no clarification about the id's origin or format, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete a tag") and immediately qualifies the scope: the definition is removed and the tag is detached from every contact and conversation. That scope sentence is what separates it from untag_contact, which only removes the tag from a single entity.

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

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

Usage is implied by the destructive scope statement, but the description never says when to reach for this versus untag_contact (detach one at a time) or update_tag-style renaming. No prerequisites or warnings about confirming before a global detach are given.

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

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

The annotations declare destructiveHint=false, yet the description says the draft is "thrown away" — the description usefully discloses that the draft content is lost while the live version survives, which the annotations do not convey. Remaining gaps: it does not say whether discarding a non-existent draft errors or no-ops (relevant given idempotentHint=false), nor whether confirmation is advisable. The tension with destructiveHint=false is mild and consistent with the common convention that discarding transient draft state is not a destructive update to live resources.

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

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

Three short sentences: identity of the action first, the consequence and the preserved state second, the call mechanics last. Nothing is redundant and the most important fact (live version is untouched) is front-loaded.

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

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

For a one-parameter mutation with no output schema, the description covers what is affected, what is preserved, and how to form the call — annotations carry the rest of the safety profile. It lacks only failure/no-draft behavior, which is a minor omission at this complexity level.

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 single `id` parameter is already documented, and the baseline is 3. "Send {} as the body" adds the useful detail that no body payload is needed, but it sits awkwardly against a schema that marks `id` as required with additionalProperties=false, leaving the agent to infer that `id` travels in the path rather than the body.

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?

"Discard a flow draft" names a specific verb and resource, and "the live version stands" immediately separates it from the sibling delete_flow, which removes the whole flow. It stops short of naming delete_flow or update_flow explicitly, so the differentiation is implied rather than stated.

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

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

The phrase "the unpublished draft" implies the precondition (an unpublished draft must exist) and implies when not to use it (when you want the live flow removed, use delete_flow). There is no explicit when/when-not statement or named alternative, so an agent must infer the routing.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses the concrete side effects: the copy is named '(Copy)', starts paused, and gets fresh stats. It also reveals two non-obvious invocation requirements — an empty JSON object body and a Content-Type header — which an agent would otherwise get wrong.

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

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

Three short sentences, each with a distinct job: what it does, what the result looks like, and the exact call mechanics. The most important facts (copy semantics, paused state) are front-loaded with no filler.

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

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

With no output schema, the description should say what comes back — critically, the new trigger's id, which the agent needs to perform the suggested 'PATCH active: true' step. The invocation mechanics and side effects are well covered, but the return value and how to obtain the copy's id are left unstated.

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

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

Schema coverage is 100% for the single 'id' parameter, so the schema already carries the meaning. The description adds nothing about which trigger id is expected (source vs. copy), leaving the schema to do all the work, which matches the baseline of 3.

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

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

The opening sentence names a specific verb and resource ('Duplicate a comment trigger') and immediately clarifies it produces a new trigger rather than modifying the existing one. This cleanly separates it from create_comment_trigger and update_comment_trigger in the sibling list.

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

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

The description makes the use case clear: copy an existing trigger instead of rebuilding one, and it explains the follow-up step ('Activate it with PATCH active: true'). It does not explicitly say when to prefer create_comment_trigger over this, but the context is strong enough for correct selection.

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

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

Annotations already declare a non-destructive, non-idempotent write with no open-world access, so the safety profile is covered. The description adds the genuinely useful fact that the copy lands as a draft rather than being published or activated. However, it says nothing about naming/collision behavior, permissions required, or side effects on the source flow.

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

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

Three short sentences, front-loaded with the action and result, with no filler. The trailing 'Send {} as the body' is efficient but slightly cryptic in a schema that marks 'id' as required, which costs a point.

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 duplication tool with no output schema, the core action is covered, but the definition never says what comes back — most importantly the new flow's id, which the agent needs to subsequently update or publish the copy. Prerequisite conditions for the source flow are also unstated.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented, so the baseline applies. 'Send {} as the body' does add a little meaning by hinting that id travels as a path parameter and the request body must be empty, but it is terse and an agent could still misread it as meaning id is omitted entirely.

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

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

The description names a specific verb and resource ('Duplicate a flow') and adds the resulting state ('Copies the flow as a new draft'), which distinguishes it from create_flow or get_flow. It does not explicitly contrast itself with any sibling, so it sits just below the top band.

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

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

Usage is only implied: wanting a copy of an existing flow rather than authoring one from scratch. There is no guidance on prerequisites (must the source flow be published? does it copy the draft or the live version?), no mention of when to prefer create_flow, and no note on what happens to the original.

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, so the safety profile is covered. The description adds what the caller actually gets back (identity, plan, key scope, webhook endpoints) and signals low cost, which matters because there is no output schema. It does not describe failure behavior for an invalid key, a notable omission given the key-verification use case.

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

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

Three short clauses with zero filler: purpose first, returned content second, and the cheapest-usage hint last. Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

For a zero-parameter read with no output schema, the description covers the essentials by enumerating the returned fields and giving a primary use case. It leaves the error path (invalid or expired key) implicit, which is the one gap an agent hitting a failure would want addressed.

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

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

With zero parameters there is nothing for the description to disambiguate, so the baseline applies. The description correctly implies a no-input call and does not invent parameter language that would confuse the caller.

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

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

The description names a specific verb and resource ("Get the account") and then enumerates what that resource contains: identity, plan, calling key and scope, webhook endpoints. That is far more concrete than a tautology. It stops short of distinguishing itself from nearby siblings such as get_overview or get_account_insights, so an agent must infer the boundary.

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

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

"The cheapest call to prove a key works" gives a clear, actionable usage context — validating credentials — which is exactly the kind of guidance an agent needs for a zero-argument tool. It does not state when-not to use it or name an alternative for account analytics, which keeps it below 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?

Substantial disclosure beyond the annotations: the call hits Instagram live, is slow, and consumes Meta rate-limit quota. It also documents the exact failure mode (403 permission_required) and the remedy (reconnect the account with the insights permission in the portal) — behavior an agent could not infer from readOnlyHint/idempotentHint.

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

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

Three short sentences with no filler: what it returns, then the operational cost, then the failure mode. The opening 'Get account insights' is a mild restatement of the name, but it front-loads the scope and metrics immediately after.

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

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

With no output schema, the description compensates by enumerating the returned metrics, and for a single-parameter read tool it also covers latency, rate limits, and the permission error path. Nothing an agent needs in order to call it correctly and interpret a failure is missing.

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

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

Schema description coverage is 100% and the enum already constrains the single parameter, so the description's mention of 'last 1, 7 or 30 days' adds no new semantics. The schema-implied default of 7 is not reiterated, which is fine given full coverage.

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

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

The description names a specific verb and resource and enumerates the exact metrics returned (reach, profile views, interactions, saves, shares, follows), scoped to 'your own account' — which separates it from competitor-facing siblings like get_competitor_leaderboard and get_audience_demographics.

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

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

It states the eligible time windows (1, 7 or 30 days) and makes clear this is a live Instagram call that costs latency and rate-limit budget, which implicitly tells an agent to call it sparingly and not inside tight loops. It does not explicitly name alternatives (e.g. get_overview or get_audience_demographics) for related metrics, so routing between them is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: with no output schema, it discloses the exact response shape (connected / AI answers / automations run per channel) and the non-obvious quirk that Facebook and Instagram share a single meta switch, which would otherwise mislead an agent counting channels.

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 padding, with the resource front-loaded in sentence one and the return fields enumerated in sentence two. The parenthetical about meta sharing a switch is the only aside and it earns its place by preventing a miscount.

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

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

No output schema exists, so the description must carry the return-value burden and largely does by naming all channels and all three per-channel flags. A small gap remains: it does not say the shape is an object/map keyed by channel, nor whether disconnected channels are omitted or returned with false values.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does still usefully name the fixed channel set (meta, sms, whatsapp, telegram) that the implicit result keys will cover.

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

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

States a specific verb+resource ("Get the per-channel AI switches") and then enumerates exactly which channels and which three properties per channel. This is far more specific than the name alone. It does not, however, differentiate itself from the sibling get_ai_config, so an agent must infer that this is the per-channel view while get_ai_config is presumably the global config.

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

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

Usage is only implied: the description makes clear this is a read of channel status, which an agent would call before toggling anything, but there is no explicit when-to-use, no prerequisite, and no reference to get_ai_config as the alternative for account-wide settings.

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, closed-world and non-destructive, so the safety profile is fully covered. The description adds that the response contains all nine sections and that file_handling, followups, csat and comment_ai are plan-entitlement booleans — useful return-content context, though it omits what the other five sections are.

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

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

Three short sentences, but the last one is awkwardly constructed ("available on file_handling, followups, csat and comment_ai says whether the plan includes that feature") and forces re-parsing. Front-loading the purpose is good; the labeling of the four flags could be far cleaner.

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 the return value, and it only partly does: it names four of the nine sections and gives no shape for the rest. Adequate to call correctly, but an agent cannot predict the payload structure.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument call that returns the full configuration.

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 the AI configuration") and adds scope ("All nine sections in one call"), which distinguishes it from narrower siblings like get_ai_channels. The final sentence is understandable as a description of entitlement flags but is grammatically garbled enough to slow an agent down.

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

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

Usage is only implied by the name — an agent can infer it should call this to inspect AI settings. There is no explicit statement of when to prefer it over get_ai_channels or other config-reading siblings, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered structurally. The description adds no behavioral context beyond that — no note on missing-record behavior, no fields returned, no permissions. With annotations the bar is lower, but nothing extra is contributed.

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 brief sentences, front-loaded with the action, with no filler. It is efficient but so sparse that brevity comes at the cost of substance.

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

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

For a single-parameter read tool with rich annotations, the description is minimally sufficient to invoke correctly. It stops short of describing the returned appointment or error behavior, which would matter 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% with one required integer 'id', and the description's 'by id' merely echoes it. Baseline 3 applies since the schema carries the parameter semantics and the description adds no format or lookup nuance.

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 pairs a generic verb with the resource and adds cardinality ('One appointment by id'), which implicitly distinguishes it from list_appointments. However, it is close to a restatement of the name/title and does not explicitly contrast with siblings like list_appointments or get_availability.

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 stated alternative for looking up appointments by other criteria, and no mention of what happens if the id is unknown. The agent must infer everything except the single-id retrieval case.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds information they cannot carry: the 404-before-first-refresh behavior and the zeros-not-errors degradation for small accounts. Those are exactly the failure modes an agent needs to interpret a bad-looking response 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?

Front-loaded with the core statement, then the data availability caveats, then the use case. Mostly tight, but 'followers online by hour' is stated twice (mid-description and again in the closing sentence), which is a small redundancy.

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

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

With no parameters, no output schema, and no nested objects, the description carries the full explanatory load and does so: it describes the return shape field by field and covers both empty-state conditions. Nothing needed to interpret a successful or failing call is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends its budget on return content and edge cases instead.

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 audience demographics') and immediately enumerates the breakdown: gender/age percentages, top countries and cities, followers online by hour. That content profile implicitly separates it from a generic sibling like get_account_insights, though no sibling is named explicitly.

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

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

Gives real operating context: 404 until the first refresh, and Instagram withholding data for accounts under ~100 followers. It also names the downstream question this answers ('when should I post'). It stops short of explicitly routing to or away from alternatives such as get_account_insights or get_follower_history.

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 closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the slot computation draws on business hours, service duration, buffer, minimum notice and existing bookings, and the 'Empty on a closed day' note flags an important edge case an agent would otherwise misread as an error.

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

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

The purpose is front-loaded in the first sentence and the whole text is three short sentences with no filler. The middle sentence is a verbless list fragment, which reads as telegraphic rather than flowing prose, but it is dense with useful information rather than padded.

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

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

For a read-only lookup with full schema coverage and no output schema, the description covers what is computed, what the result represents, and the empty-result case. Return shape details (list of timestamps vs. free/busy windows, timezone of the returned slots) are not stated, which is the main remaining gap.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema, making 3 the baseline. The description reinforces that the output is scoped to a single day and hints that service duration affects slot length, but it adds no syntax, format or interaction detail (e.g. how city/state interact with service_type) beyond what the schema states.

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

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

The description states a specific verb+resource ('Get availability... the open slots for one day') and enumerates the inputs that shape the result: business hours, service duration, buffer, minimum notice, existing bookings. It is clear what the tool returns, but it never names a sibling such as book_appointment or list_appointments, so differentiation is only implicit.

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

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

Usage is only implied: an agent can infer this is the pre-booking slot lookup, and 'What the bot and the portal picker offer' signals that results match the customer-facing surfaces. There is no explicit 'call this before book_appointment' instruction and no statement of when not to use it or what to do if the result is empty.

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 establish that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful behavioral context by saying the counts are measured against plan caps and by identifying the approval queue metric, but it does not explain update frequency, timezone boundaries for 'today', or response shape.

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

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

The description is two sentences and front-loads the purpose before listing metrics. The first sentence largely restates the tool name, but it is short enough that it does not obscure the useful metric details.

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

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

For a zero-parameter, read-only stats tool, the description identifies the main metric categories and the plan-cap comparison. It is slightly incomplete because there is no output schema and the description does not specify the exact response structure, but it is sufficient for an agent to understand what the call returns.

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?

This tool has zero parameters, so there is no parameter semantics to add. The baseline for a zero-parameter tool is 4, and the description does not create any misleading parameter expectations.

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 (get comment manager stats) and enumerates the exact metrics covered: pending reply approvals plus today/month handled, replied, and moderated counts versus plan caps. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling get_comment_trigger_stats 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?

The description describes the stats returned but gives no explicit guidance on when to use this tool versus alternatives such as list_handled_comments or get_comment_trigger_stats. Usage is only implied by the metric list, so an agent must infer the appropriate context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's one addition is that the response embeds the trigger's linked flows, which is useful return-shape context absent from any output schema. It reveals nothing about not-found behavior or error cases.

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 verb and resource, with no filler. The first sentence largely restates the annotation title, which is a minor redundancy rather than waste.

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

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

For a simple one-parameter read tool with complete annotations, this is nearly sufficient: it identifies the target, the lookup key, and the notable return content. Only not-found and error semantics are left unstated.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the id field. The description's "by id" is consistent with the schema but adds no new meaning such as id source or format caveats. Baseline 3 applies when the schema carries the documentation burden.

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 a comment trigger") and clarifies the scope as a single record retrieved by id, which distinguishes it from the sibling list_comment_triggers by singular vs plural. It does not explicitly name the listing sibling as an alternative, so it stops short of full differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as list_comment_triggers. The single-record framing implies a lookup, but the agent must infer the selection criteria entirely.

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 closed-world, so the safety profile is covered. The description still adds real behavioral value by specifying that the counters are 'lifetime' (i.e. cumulative with no date-range filtering available) and that results are 'split by channel', which an agent cannot learn from the annotations or the one-field schema.

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

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

Two sentences, front-loaded with the action and scope, followed by a compact enumeration of returned counters. No filler, no restatement of the title beyond the necessary opening clause.

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

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

With no output schema, the description carries the burden of describing returns, and it does list every notable counter and the channel split. It stops short of saying how those values are shaped (flat numbers vs. per-channel breakdown objects) or what is returned when a trigger has never fired, which is a minor gap for a read-only stats tool.

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

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

There is a single parameter at 100% schema coverage, where the schema says 'Numeric id.' The phrase 'for one trigger' clarifies that the id identifies a comment trigger rather than a post or flow, but no further meaning (where to obtain the id, error behavior for unknown ids) is added. Baseline 3 applies.

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

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

States a specific verb and resource ('Get comment trigger stats') and immediately scopes it to 'one trigger', then enumerates exactly what is counted (fires, public replies, DMs, AI-written DMs, link clicks, unique people, per channel). This clearly separates it from a config-read sibling like get_comment_trigger and from the account-wide get_comment_manager_stats, though it never names those siblings explicitly.

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

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

Usage is only implied: an agent can infer this is the metrics view rather than the configuration view, but the description gives no explicit 'use this when you want performance numbers, use get_comment_trigger for settings, use get_comment_manager_stats for the aggregate' guidance. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description still earns credit by adding data-freshness context that annotations cannot express: results come from 'stored snapshots, no Meta call', telling the agent figures may be stale and that the call is cheap and offline. It does not explain behavior for an unknown or unlinked competitor id.

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

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

Three short sentences, front-loaded with the action and followed by the result shape and the data-source caveat. Nothing is wasted, though 'the per-metric differences the portal shows' is slightly circular phrasing.

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

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

With no output schema, the description does the work of telling the agent what comes back: competitor and own account side by side plus per-metric deltas. For a one-parameter read tool with full annotation coverage this is nearly complete; only error/empty-competitor behavior is unaddressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema's param text is just 'Numeric id.', but the description's 'compare against one competitor' usefully implies the id identifies that competitor rather than an account or post; it adds no format, validation or lookup hints beyond that.

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 scope: compare against exactly one competitor. It implicitly separates this from list_competitors and get_competitor_leaderboard via the 'one competitor' framing, though it never names those siblings explicitly.

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

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

Usage is only implied: reach for this when you need a head-to-head for a single competitor. There is no explicit when-not guidance and no pointer to the leaderboard/overview tools for the multi-competitor or aggregate case, so the agent must infer the routing itself.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by disclosing that results come from stored snapshots, are instant, and consume no Meta quota. It doesn't say how stale the snapshot may be or that refresh_market_intel exists to update it, which is the one behavioral gap.

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?

Metrics are front-loaded and the quota/snapshot note earns its place, but "Your account and every competitor ranked together" is repeated verbatim in two separate sentences, which is unambiguous waste. The "table behind the portal's Market Intel page" line is useful orientation but adds length to an already-redundant paragraph.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description supplies what the schema cannot: what fields the ranking actually contains. Only the snapshot freshness/refresh path is unaddressed, which is minor for a cached read.

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

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

Schema coverage is 100% and the single enum parameter already documents the 7/30/90 window and default of 30. The description adds no syntax, default, or interpretation detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource and enumerates exactly what is ranked: followers, engagement rate, posts per week, average likes/comments, follower growth per day, and content mix. It also disambiguates from neighbors like get_competitor and get_wins_and_opportunities by framing the tool as the combined account-vs-competitor comparison table.

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?

"Start here for any 'how do I compare' question" gives explicit entry-point guidance for a whole class of queries. It stops short of naming an alternative (e.g. get_wins_and_opportunities for the diagnostic follow-up, refresh_market_intel for fresher data), so the when-not-to-use case is left implicit.

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 fully covered by structured data. The description adds no behavioral context beyond that — it says nothing about error behavior when the id doesn't exist, permissions required, or what a contact record contains.

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

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

It is short and front-loaded, but the second sentence ('One contact by id.') largely restates the first instead of earning its place with new information. Two sentences where one well-built sentence would carry the same payload.

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?

This is a simple one-parameter read tool with full schema coverage and rich annotations, and there is no output schema, so the description needn't explain return values in depth. However, nothing indicates what identifying key 'id' refers to (CRM contact id vs. external id) or what the agent gets back, leaving a small but real gap for a retrieval tool.

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

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

Schema description coverage is 100% (the single 'id' parameter is documented as 'Numeric id.'), so the schema carries the parameter semantics. The description only restates 'by id' and adds no meaning such as id source, format constraints, or what happens with an unknown id; 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 ('Get a contact') plus the addressing mode ('One contact by id'), so an agent knows this is a single-record retrieval. It does not distinguish itself from siblings like list_contacts, get_account, or upsert_contact, which is the one thing keeping it from a 5.

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

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

The phrase 'One contact by id' weakly implies 'use this when you have an id and need exactly one contact', but there is no explicit when-to-use, when-not-to-use, or named alternative. With list_contacts and upsert_contact in the sibling list, the agent must infer the routing decision on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what happens when the id is unknown, no indication of what a conversation record contains.

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

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

Two very short sentences with the core action front-loaded; no padding or preamble. The second sentence largely restates the first, so it is efficient but slightly redundant.

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

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

For a one-parameter read tool with no output schema, the definition covers the minimum: what it fetches and by what key. It omits error behavior for a missing id and any hint about the shape of the returned conversation, leaving the agent to discover those.

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% for the single parameter, and the schema already documents it as a numeric id. The description's "by id" merely echoes that, adding no format, range, or provenance detail beyond the schema.

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

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

"Get a conversation" names a specific verb and resource, and "One conversation by id" scopes it to a single record, which implicitly separates it from list_conversations. It does not explicitly name that sibling, so the differentiation is inferable rather than stated.

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

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

There is no when-to-use guidance: nothing says to call this only after obtaining an id from list_conversations, or how it relates to list_messages or update_conversation. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The one genuinely additive fact is "metadata only", which tells the agent the document body is not returned — a real behavioral detail not encoded in any structured field. Beyond that (error behavior for missing ids, what metadata fields exist) nothing is disclosed.

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

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

Two short sentences, front-loaded with the action and immediately narrowed to the by-id, metadata-only scope. "Get a document." is partially redundant with the sentence that follows, but the total length is small enough that nothing meaningfully burdens the agent.

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

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

For a one-parameter read tool with rich annotations and no output schema, the description covers invocation adequately. It is thin on returns, though: with no output schema present, the phrase "metadata only" is the sole signal about what comes back, and it doesn't indicate which metadata fields or what happens for an unknown id.

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

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

Schema description coverage is 100% for the single id parameter, so the schema already carries the semantics and the baseline is 3. The description's "by id" phrasing matches and lightly reinforces the lookup key, but adds no format, range, or error semantics 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?

"Get a document. One document by id, metadata only." names a specific verb and resource and constrains the scope to a single item by id, plus a key qualifier that only metadata is returned. It does not, however, differentiate itself from siblings like list_documents or update_document, so an agent must infer the boundary from names alone.

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

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

Usage is only implied: fetch a single document when you already have its numeric id and want metadata. There is no explicit when-not guidance, no mention of what to use instead if the document body is needed, and no pointer to list_documents for discovery.

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 fully covered without the description. The description adds nothing beyond that: no error behavior for a missing id, no note on response contents. With the annotations carrying the burden, this is thin but not contradictory.

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 verb and resource. The second sentence largely restates the first, so it is slightly redundant but far from verbose.

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

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

This is a simple single-parameter getter with rich annotations and full schema coverage, so little is required. However, with no output schema, the description says nothing about what an FAQ record contains or what a not-found response looks like, leaving a modest 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% with a single documented integer id parameter, so the schema does the work. The phrase "by id" adds no format, range, or lookup semantics beyond what the schema states; baseline 3 applies.

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

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

"Get an FAQ" gives a specific verb and resource, and "One FAQ by id" clarifies the singular scope, implicitly distinguishing it from the sibling list_faqs. It stops short of naming the sibling or describing what an FAQ record contains, so it is clear but not maximally differentiating.

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

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

There is no explicit when-to-use guidance, no mention of the list_faqs alternative, and no preconditions such as required permissions or behavior when the id does not exist. The usage is only implied by the word "Get."

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 establish a read-only, idempotent, non-destructive operation, and the description does not conflict with them. Beyond restating single-record retrieval, it adds no behavioral context such as draft or published-state handling, not-found behavior, or the returned representation.

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 extremely compact and puts the operation first, with the second sentence adding single-record lookup scope. Its wording is somewhat redundant and fragmentary, but there is no substantial unnecessary material.

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 getter, the definition is sufficient to construct a call, and the annotations cover its safety profile. It is less sufficient for choosing confidently among get_flow, list_flows, and get_flow_definition, or for knowing whether the result is metadata, a full flow, or a draft, with no output schema to fill that 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%, and id is already required, integer-typed, and described as "Numeric id." The description's "by id" adds retrieval cardinality but no new parameter semantics such as ID provenance or lookup constraints, so the fully documented schema baseline 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 supplies a clear verb and resource and narrows the operation to retrieving one flow by ID. It does not distinguish the returned flow from the sibling get_flow_definition, so it is clear but not differentiated from relevant siblings.

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

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

The phrase "One flow by id" implies use when a specific numeric ID is already known, so the usage context is partially inferable. It never directs agents to list_flows for discovery or get_flow_definition for definition content, and provides no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral caveats: only tracked sessions are counted, other_version_runs_excluded quantifies runs under a different version, and comparison is null for range=all. It does not mention auth or rate limits, but for a read-only reporting call those gaps are minor.

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

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

The purpose sentence is front-loaded, and the long metric enumeration is dense but each item is informative for an agent that cannot see an output schema. There is minor redundancy (the comparison-window point is stated twice, once in prose and once in the schema) and the single-paragraph form makes the metric list hard to scan.

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, this description carries the full burden of explaining the return payload, and it does so thoroughly — window metrics, comparison window, lifetime totals, outcomes, per-node reach/continue/response/loss rates, per-port branch splits, and the versions list. Combined with the tracking-only caveat, an agent has enough to interpret the result correctly.

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

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

Schema description coverage is 100%, so the schema already explains id, range, channel and version, including the 7d/30d/90d/all enum and the comparison-null note. The description adds only modest value beyond that — chiefly that the response's 'versions' list is how an agent discovers valid version numbers not covered by an enum — so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Get flow analytics') and immediately scopes it to 'the builder's Analytics panel for one flow', then enumerates the exact metrics returned. This distinguishes it clearly from siblings that deal with raw flow data (list_flow_sessions, list_flow_events, get_flow_definition) 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?

It gives useful scoping context — analytics are per published version, version defaults to the current one, and 'versions lists the others' — which tells the agent how to get meaningful results. However, it never names an alternative tool or states when to prefer raw session/event listings over aggregate analytics, so the when-to-use-with-what guidance is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, but the description adds genuinely new information: the returned definition is the draft when one exists, otherwise the published version. That resolution logic is real behavioral context an agent could not derive from the annotations or schema.

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

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

Two short sentences, front-loaded with the action and immediately followed by the scoping/fallback rule. Every clause carries information; nothing is padding.

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 some work on the return value by stating it is the draft-or-published definition, but it says nothing about the structure or size of that definition. For a single-parameter read tool this is nearly complete, with only the shape of the returned payload left implicit.

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

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

There is a single parameter with 100% schema description coverage ("Numeric id."), so the schema already carries the burden. The description adds no further meaning about what the id refers to or how to obtain it, making the baseline 3 appropriate.

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

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

The description gives a specific verb and resource ("Get a flow definition") and clarifies scope with "The definition alone," which implicitly separates it from siblings like get_flow. However, it never names those siblings, so an agent must infer the distinction rather than being told.

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

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

Usage is only implied: "the definition alone" hints that this fetches the raw definition body whereas other flow tools fetch metadata or catalogues. There is no explicit when-to-use guidance, no named alternative, and no stated preconditions.

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, closed-world, non-destructive behavior, so the safety profile needs no repeating. The description still adds real value beyond them by disclosing that the payload is partly account-scoped (custom fields, tags, services, existing flows, comment triggers, plan caps), which tells the agent the result varies per account and can be used to plan around limits. It says nothing about response size or shape, which is the main remaining gap.

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 content is front-loaded and information-dense, but the last two sentences restate material already given: "Read this before writing a flow definition" duplicates "Read it before composing a definition," and "It lists every node type, its config fields and output ports" repeats the list in sentence two. Roughly a third of the description is redundant, which costs it on this dimension.

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 input parameters and no output schema, the description carries the full burden of telling the agent what comes back, and it does so thoroughly by inventorying trigger sources, node types, ports, enums, placeholders, rules, and account-specific options. What it omits is any sense of payload shape or size, which matters for a catalogue payload this broad, so it falls just short of 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 no parameters, so there is no per-argument meaning to add; baseline 4 applies. The description correctly describes a zero-argument call, leaving nothing ambiguous about invocation.

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 verb and resource ("Get the node catalogue") and then enumerates exactly what the catalogue contains: trigger sources with channels and keyword requirements, node types with input/output ports and config fields, enums, placeholders, structural rules, plus live account data. That enumeration makes it unmistakable versus siblings like get_flow_definition or get_flow, which return actual flows rather than the build-time vocabulary.

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 directive is explicit and repeated: read it before composing a flow definition. That is clear when-to-use guidance. It stops short of naming alternatives (validate_flow, create_flow) or an explicit when-not-to-use case, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that: no note on what a session contains, whether ids are tenant-scoped, or what happens with an unknown id. With annotations doing all the work, this is a minimal contribution.

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 fragments, front-loaded with the action and no filler. The second sentence is nearly redundant with the first, but the size is well matched to the tool's simplicity.

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

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

For a tool with no output schema, the description carries the burden of explaining what is returned, and it says nothing about the session object's contents, shape, or error behavior. Combined with zero usage guidance among many flow-related siblings, an agent has to guess at both selection and interpretation.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the id. "By id" in the description merely echoes the schema's "Numeric id." and adds no format, provenance, or lookup semantics, so the baseline of 3 applies.

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

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

"Get a flow session. One session by id." names a verb and resource, but it largely restates the tool name and title. The phrase "one session by id" adds a hint of singular retrieval, distinguishing it weakly from list_flow_sessions, yet the sibling is never named and the distinction is left implicit.

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 instead of list_flow_sessions, list_flow_session_events, or get_flow. The agent must infer that this is the single-record lookup from the word "one" alone, with no prerequisites or exclusions stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: one series per account including the caller's own, oldest-point-first ordering, one point per snapshot day, and that gaps mean nobody refreshed — all of which prevents misreading the data.

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

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

Three short sentences, front-loaded with the core purpose, then output composition, then the data-granularity caveat. Nothing is redundant with the title or schema, and every sentence carries information an agent needs.

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

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

With no output schema, the description bears responsibility for explaining return values, and it does so well: metrics, per-account series, ordering, and gap semantics. The only gap is the concrete container/shape of the response (e.g., whether series are keyed by account id), which would make it fully self-sufficient.

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

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

Schema coverage is 100% and the single 'period' parameter is fully documented with its enum and default, so the schema carries the load. The description only refers to 'the window' without adding format or interpretation detail beyond that, which is the expected baseline when the schema is complete.

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

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

The description names a specific resource (follower history) and immediately specifies the metrics returned — follower count and engagement rate — plus the per-account series structure. It is clearly distinguishable from sibling analytics tools like get_overview or get_account_insights, though it never explicitly compares itself to them.

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

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

Usage is implied by describing a time-windowed trend series, which tells an agent this is for historical/trend questions rather than a current-state lookup. However, there is no explicit when-to-use versus when-not, and no mention of the sibling insight tools an agent might otherwise pick.

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, so the safety profile is fully covered without the description. The sentence "One log row by id" adds a small amount of behavioral context about the result shape (a single record identified by id), but it says nothing about error behavior when the id does not exist.

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 operation and then the return shape, with no filler. The second sentence is a fragment, which slightly reduces readability but wastes no words.

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

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

Wait — recomputing against complexity: the tool is a simple one-parameter read with full schema coverage and complete annotations plus no output schema, so the description does not need to explain return fields. What is genuinely missing is the meaning of a 'handled comment' and the not-found behavior. Hmm, that gap is real. Reassessing: the definition is adequate for a trivial get-by-id, but the term 'handled comment' is the whole resource and is left undefined, and no fallback is described for a missing id. That is a moderate gap rather than a severe one, so 3 fits better than 4. Final: 3.

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 required parameter with 100% schema description coverage, so the schema already carries the burden. The description only restates that lookup is 'by id' and adds no format, range, or provenance guidance (for example, where valid ids come from), so it does not exceed the baseline.

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 and resource ("Get a handled comment") and clarifies the return granularity as "one log row by id," so the basic operation is discernible. However, "handled comment" is never explained, and with a sibling named list_handled_comments the description does nothing to distinguish single-fetch from list behavior.

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 mention of prerequisites such as needing an id from list_handled_comments, and no named alternative. The agent must infer the relationship to list_handled_comments and the approve/reject sibling tools entirely on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the result (counts vs plan cap, per-category breakdown, storage) and its role as a gating check before creation. No auth or rate-limit context, but that is minor for a read-only usage endpoint.

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

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

Three short sentences, front-loaded with the purpose, then the return contents, then the actionable workflow hint. No filler or redundancy.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so adequately by naming the counts, breakdown and storage figure. It could be slightly richer (e.g. whether the cap is a hard limit or what happens at 100%), but an agent has enough to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no filtering or scoping inputs 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 knowledge base usage') and then enumerates exactly what is returned: item counts against the plan cap broken down by FAQs, services and documents, plus document storage. This clearly separates it from listing siblings like list_faqs or list_documents, though it doesn't name those siblings explicitly.

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

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

The closing sentence 'Check can_add before creating' gives a concrete pre-flight workflow, which is real when-to-use guidance. It stops short of stating when not to use it or naming a direct alternative, so it falls just short of a 5.

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

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

Beyond the read-only and idempotent annotations, it discloses same-data-layer parity with the portal, rolling current/previous comparisons, comment-trigger attribution that prevents double counting, and the billing-cycle exception for usage. These are material calculation and scope behaviors that affect interpretation of the results.

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

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

The purpose is front-loaded and the three sentences contain substantial useful information with little redundancy. The long middle sentence and nested parenthetical make the metric inventory harder to scan than a structured list would.

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 one optional parameter, it supplies enough scope, comparison, and content information to support correct selection and invocation despite the absence of an output schema. It is less complete about response organization and leaves phrases such as 'what needs a human' and appointments 'with the next few' somewhat 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?

The schema already documents the allowed ranges, default, and equal-length previous window. The description adds the important scope rule that plan usage remains billing-cycle based regardless of range, though it does not further define window boundaries or timezone behavior.

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 verb and resource are specific, and mapping the result to the portal's Overview page establishes this as an account-wide aggregate. The cross-domain metric inventory also distinguishes it from narrower siblings covering flow analytics, comment-trigger statistics, or knowledge gaps.

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 clearly supports cases where the agent needs the portal Overview numbers or a broad current-versus-previous account summary. It does not explicitly say when to prefer specialized alternatives such as get_account_insights, get_flow_analytics, or get_comment_trigger_stats.

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 read-only, idempotent, non-destructive, closed-world behavior. Beyond that, the description adds useful detail about the returned payload: media, published ids, and any error. It does not describe auth requirements, not-found behavior, or pagination, but for a simple get-by-id tool it adds meaningful context beyond 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?

The description is two short sentences and front-loads the core operation. The first sentence ('Get a post.') is slightly redundant with the tool name and title, but the second sentence efficiently adds return-content 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?

For a simple one-parameter read tool with annotations covering safety and no output schema, the description is largely complete because it explains the key returned contents. It could be more complete by mentioning lookup-by-id or error conditions, but the essential context is present.

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

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

Schema description coverage is 100%, with the sole 'id' parameter documented as a numeric id. The description does not mention the parameter at all, so it adds no meaning 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 states a specific verb and resource ('Get a post') and clarifies the scope as one post rather than a list, which distinguishes it implicitly from list_posts. It does not explicitly name a sibling alternative, but the singular scope makes the purpose clear.

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

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

Usage is only implied: retrieving a single post by its id, with list_posts presumably used for listing. There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives such as list_recent_posts.

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 closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: values are live from TikTok, degrade to a safe fallback, and caps are reported with current usage (i.e. a mutable snapshot). It does not explain the fallback's shape or error behavior.

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

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

A short lead sentence followed by a single colon-delimited list, so the purpose is front-loaded. The list is dense and each item names a distinct returned fact, though the long clause about the TikTok creator's privacy levels and video limit is slightly run-on.

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

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

With no output schema, the description must carry the return payload, and it does so by enumerating every category of data returned. It stops short of describing the response's structure, nesting, or how the TikTok fallback is signaled, which leaves a small gap for a discovery-type tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly implies the call is argument-free and result-deterministic per account.

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

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

The description opens with a specific verb+resource ('Get posting capabilities') and then enumerates exactly what is returned: connected targets, TikTok privacy levels and video limit, post types, and plan caps with current usage. An agent can tell this apart from siblings like get_account or get_overview 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?

'What to read before building a post' explicitly frames the call as a pre-flight step before create_post/schedule_post. It gives a clear trigger condition but does not name an alternative tool or state when not to call it, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what happens when the id does not exist, or whether the id refers to a service record vs. a flow/etc. For an annotated tool this is minimal added value.

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

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

It is short and front-loaded, but the second sentence is redundant with the first and the brevity stems from under-specification rather than tight editing. One sentence could have carried the same plus more.

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

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

For a single-parameter read tool with rich annotations and no output schema, little is strictly required. Still, the description says nothing about what a 'service' is in this domain or what the response contains, leaving the agent to guess relative to siblings like get_faq or get_flow.

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

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

Schema coverage is 100% and the single parameter 'id' is documented as a numeric id. The description's "by id" adds no format, source, or lookup semantics (e.g., how to obtain a valid id, whether it comes from list_services). Baseline 3 applies when the schema carries the load.

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 verb and resource are named ("Get a service"), which is more than a bare restatement of the name, but the second sentence ("One service by id.") only rephrases the first. Nothing distinguishes it from siblings like list_services or get_faq, so an agent gets the gist but no differentiation.

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

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

There is no when-to-use guidance, no mention of list_services for enumeration vs. single retrieval, and no prerequisites or error conditions. The agent must infer usage purely from the name.

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

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

Annotations already cover the read-only, idempotent, closed-world safety profile, yet the description still adds real behavior: results come from stored data and may be stale, ordering is newest-first, and the exact metric set is enumerated. It does not mention pagination or result caps, but the staleness and ordering disclosure is exactly the kind of context annotations cannot express.

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 action and the returned fields, then ordering, then the staleness caveat — a sensible information order with no filler. Slight redundancy between "top posts" and "your own recent posts," which reads like a hedge rather than two distinct facts.

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

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

With no output schema, the description compensates well by listing returned metrics and stating sort order and data freshness. The remaining gap is that a tool named "top posts" never explains whether anything is ranked by performance, nor how it differs from list_recent_posts.

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 optional limit parameter at 100% schema description coverage, so the schema already conveys range and default. The description says nothing about limit, which is acceptable given full coverage, but it adds no meaning beyond the schema and does not explain whether limit applies before or after any ranking.

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 concrete verb and resource ("List your top posts") and immediately enumerates the metrics returned, so an agent knows what it gets. The phrase "Your own recent posts" clarifies scope, but it leaves ambiguity against the sibling list_recent_posts, which is not named or distinguished.

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

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

Usage is only implied: "Stored, so refresh first for current numbers" is a useful prerequisite hint, but there is no explicit when-to-use statement, no exclusions, and no routing to alternatives despite list_posts, list_recent_posts and get_post all being plausible substitutes.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real context beyond them: the 30-day comparison window and the fact that values come from stored snapshots with no AI involved, which tells an agent the data may be stale and is deterministic. It does not say how to force freshness, but that is what the sibling refresh tool is presumably for.

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

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

Three short sentences, front-loaded with the resource name and immediately followed by the definitions an agent needs. Every clause carries information — the time window, the two categories, the per-item fields, and provenance — with no filler.

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

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

With no parameters and no output schema, the description carries the burden of describing return content, and it does: a per-competitor set of wins and opportunities, each with a metric and gap size over a 30-day window. What is missing is any sense of scale, ordering, or whether an empty result means 'no competitors configured' versus 'no gaps found' — minor, but an agent would want 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not invent implicit filters, correctly matching the empty schema.

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

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

The description states a concrete verb+resource (get wins and opportunities) and then defines both terms precisely: wins are where you are ahead, opportunities are where the competitor is, each carrying a metric and gap size. That definition removes most ambiguity. It stops short of naming a sibling (e.g. get_competitor_leaderboard or refresh_market_intel) for contrast, which keeps it from a 5.

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

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

Usage is only implied: phrasing the output as 'comparisons already computed' and 'derived from stored snapshots' hints this is a read of precomputed data rather than a recomputation, which subtly points an agent away from refresh_market_intel. There is no explicit when-to-use, when-not-to-use, or prerequisites (e.g. whether competitors must be added first).

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 two genuinely new facts beyond those annotations: results are scoped to in-chat bookings and are ordered newest first. It omits pagination behavior (cursor paging, default page size of 25) even though that is the main operational trait of a list endpoint.

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

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

Two short, front-loaded sentences with no filler. The second is a sentence fragment that packs ordering and scope together, which is efficient but makes the scope constraint slightly harder to parse than a full clause would 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 zero-required-parameter, read-only list tool with full schema coverage and no output schema, most of what an agent needs is in structured fields. Still missing is how pagination terminates and whether the "in-chat bookings" scope means non-chat appointments are excluded entirely, both of which affect correct invocation and interpretation of results.

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 limit, status, starting_after and conversation_id are each documented in the schema, including the default of 25, the 1-100 range, the next_cursor convention, and the note that status is unvalidated. The description adds nothing about parameters beyond the ordering claim, 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 concrete verb and resource ("List appointments") plus a scope qualifier ("In-chat bookings") and an ordering ("newest first"), which distinguishes it from get_appointment and book_appointment. It stops short of saying explicitly that it is the enumeration counterpart to get_appointment, and "In-chat bookings" is left slightly ambiguous as to whether it is a hard filter or just a hint.

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

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

The word "List" plus the plural resource implies the browse/enumerate case, and the ordering hint supports that. However there is no explicit when-to-use/when-not guidance, no mention of using get_appointment for a single record, and no statement of prerequisites or auth requirements.

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, non-destructive and closed-world, so the safety profile is covered. The description adds one real behavioral fact beyond that: results are not paginated, meaning the caller receives the complete set in one response and needs no cursor handling. It stops short of describing what fields each entry contains.

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

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

Two short sentences, front-loaded with the action and immediately followed by the definition of the resource and the pagination caveat. There is no filler or restated name/title boilerplate.

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

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

For a parameterless read tool with no output schema, the description covers what is returned, the scope of "blocked," and the response shape constraint (unpaginated). The one gap is the absence of any hint about the fields or count returned per entry, which matters slightly given there is no output schema to fall back on.

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 and the baseline is 4. The description correctly implies a single unscoped call with no filters, consistent with the empty schema.

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

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

The description states a specific verb and resource ("List blocked users") and disambiguates the term "blocked" as "everyone the AI is currently refusing to answer," which is genuinely clarifying. It does not explicitly contrast with neighboring list tools such as list_opt_outs or the block_user/unblock_user pair, so it stops short of full sibling differentiation.

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

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

Usage is only implied: an agent can infer this is the read-side companion to block_user/unblock_user, but the description never says when to call it versus list_opt_outs or how it relates to those tools. No exclusions or prerequisites are given.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavior: results are ordered newest first and each entry is joined with its linked flows, which an agent cannot infer from the schema. The native-trigger exclusion is also scope-relevant, though phrased in a way that takes effort to parse.

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

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

The core scope is front-loaded in the first two sentences, which earns the opening. The third sentence is a single 30-plus-word clause with an aside in parentheses and a raw path reference ('/flows', 'mode native'), which reads as internal spec leakage rather than agent-facing guidance.

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 sensibly discloses the return shape (triggers plus linked flows) and ordering, which is what an agent needs before iterating. Pagination is handled by the documented starting_after parameter, so the remaining gap is minor; only the confusing native-trigger wording weakens 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% and each of the six parameters, including the two enums, is already documented in-schema. The description adds no filter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

First sentence states a specific verb and resource ('List comment triggers') and the second narrows the scope to 'Standalone comment triggers, newest first, each with the flows linked to it.' It is distinguishable from get_comment_trigger and from list_flows by the standalone qualifier, though the scope distinction is buried in a dense third sentence.

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 an implied when-not: flow-embedded 'native' triggers are excluded and live on /flows instead, which routes the agent in one direction. However, nothing says when to prefer this over get_comment_trigger, get_comment_trigger_stats, or list_flows, and no prerequisites or pagination guidance are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: no pagination (whole set in one page), plan-based slot ceilings (Free 1, Creator 3, Pro 5, Business 10), and the fact that last_snapshot_date is null until the first refresh.

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

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

Five short sentences, front-loaded with the purpose and payload, then plan limits, then the no-pagination and null-date caveats. No sentence is filler; the plan-tier list is dense but earns its space by telling the agent what the slot numbers mean.

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

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

With zero parameters, rich annotations, and no output schema, the description covers enough to call it correctly: what is returned, that it is unpaginated, and a null-value edge case. It stops short of describing the per-entry shape beyond "numbers from its latest snapshot," which leaves some return-format ambiguity against the absence of an 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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing in the input schema for the description to clarify or contradict.

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

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

States a specific verb and resource ("List tracked competitors") and immediately scopes the payload: every tracked account, its latest snapshot numbers, and plan slot counts. This is clearly distinguishable from get_competitor (single account), add_competitor, and remove_competitor.

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

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

Usage is implied by the return description – an agent can infer this is the discovery/enumeration call before drilling into get_competitor – and "Whole set in one page" signals no pagination loop is needed. However, there is no explicit when-to-use or when-not-to-use statement, and no named alternative.

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