Mojeeb

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

Goes beyond the annotations with real behavioral detail: the conversation's lead is reassigned along with it (a side effect an agent must know before mutating), and the assignment is audited as made by the API key's creator. It also enumerates authorization failures (403 agent_not_authorized, 404 agent_not_found/not_found, 422 assignee_not_allowed). It stops short of saying whether the new assignee is notified or whether a previous assignee is cleared.

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 body is dense and front-loads the core semantics (assign vs unassign) before prerequisites and error codes. The opening line duplicates the tool title verbatim, which is a minor waste, but every subsequent 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?

For a four-parameter mutation with no output schema, it covers prerequisites, side effects, audit attribution, and the main error paths, which is close to complete. The remaining gap is the return value or observable result of a successful call, which the description never mentions despite there being 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?

Schema coverage is 100%, so the baseline is 3; the description earns above-baseline credit by tying assigned_to to its valid source (listAgentMembers user_ids with can_open_agent true) and by reassuring that the field is required so an empty body cannot accidentally unassign. The reason parameter is left entirely to the schema.

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

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

States the specific verb and resource ('Assigns the conversation to a teammate') and explicitly covers the inverse operation ('unassigns it with "assigned_to": null'), which no sibling does. The resource is unambiguous against siblings like assign_lead, so an agent can tell which entity is being mutated 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?

Gives a clear precondition for valid use ('The teammate must be able to open the agent: a user_id from listAgentMembers with can_open_agent: true') and maps the failure to a concrete code ('422 assignee_not_allowed'), which is genuinely actionable routing information. It does not, however, name alternatives or state when *not* to use this tool versus assign_lead or update_conversation.

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=false, idempotent=true and destructive=true, and the description adds real context beyond them: the assignment cascades to the lead's conversation, an empty body can never accidentally unassign, and the audit record is attributed to the key's creator. That is exactly the mutation semantics an agent needs and cannot infer from the hints.

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 action, then preconditions and edge cases in descending order of importance. The opening line duplicates the title, and the closing note about Mojeeb recording the assigner is tangential but short.

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

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

For a mutation tool with no output schema, the description supplies the missing pieces an agent needs: unassign path, assignee eligibility rule, error codes, idempotent re-assign behavior, and side effects on the conversation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's notes on `assigned_to` (null unassigns, must be a can_open_agent member) largely restate what the schema property descriptions already say, and the `reason` parameter is not elaborated at all.

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 the specific verb+resource and immediately covers both directions of the operation, including the exact unassign trigger (`"assigned_to": null`). It is clearly distinguishable from the sibling assign_conversation (leads vs conversations) without opening either schema.

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

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

Explicitly names the precondition (the `user_id` must come from `listAgentMembers` with `can_open_agent: true`) and the failure mode (`422 assignee_not_allowed`), plus the edge case that re-assigning to the same teammate is allowed. It doesn't spell out when to prefer this over other lead tools, but the dependency routing is strong.

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

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent), and the description adds non-obvious behavior: the note is authored by the API key holder and appears on the dashboard timeline. It doesn't state rate limits or whether notes can be deleted, but the signing behavior is genuinely useful context beyond the 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?

Two short sentences, front-loaded with the purpose and followed by behavioral context. No filler, though the restated title as the first line is mildly 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 three-parameter, non-destructive mutation with full schema coverage and annotations, the description is adequate. However, it omits usage guidance relative to siblings and does not mention any response shape, which would help since 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 detailed error semantics for each parameter (422, 404, 403). The description adds nothing about parameters, so the baseline 3 applies when the schema fully documents them.

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 (Add) and resource (note to a contact), clearly distinct from siblings like update_contact_note or list_contact_notes. It doesn't explicitly differentiate itself from those siblings, but the creation semantics are 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?

No when-to-use guidance, no mention of alternatives like list_contact_notes or update_contact_note, and no note about whether this can be repeated. The agent must infer applicability from the name alone.

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=false and openWorldHint=false, so the safety profile is largely covered. The description adds one genuinely useful behavioral fact the annotations don't convey — the AI context is rebuilt in the background, usually within a minute — but says nothing about duplicate creation, the effect on existing knowledge, or auth requirements beyond what the schema carries.

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?

Very short and the useful latency detail is present, but the first line duplicates the tool title verbatim, so roughly half the text is redundant rather than informative.

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 4-parameter mutation tool with no output schema, the description answers the important post-call question (background rebuild timing) but leaves the created resource's identity and its relationship to replace_knowledge_base undefined. Annotations partially compensate for the missing behavioral depth.

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 50%: content and agent_id are richly documented in the schema, but name and tags have no descriptions anywhere. The description's 'Text knowledge' only loosely reinforces the plain-text nature of content and adds nothing for the other two parameters.

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

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

Clear verb+resource: it adds text knowledge to a specific agent, and the name/title pair is coherent. However it never distinguishes itself from the close sibling replace_knowledge_base (or get/list_knowledge_base), so an agent can't tell from the description whether this creates a new entry or appends to an existing knowledge base.

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

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

No when-to-use, when-not-to-use, or alternative-tool guidance. With replace_knowledge_base sitting right next to it in the sibling list, the description's silence on the create-vs-replace choice is a real gap.

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 that this is a non-idempotent, non-destructive write. The description adds genuinely useful behavioral context beyond them: the lead starts in the agent's configured starting status (`new` by default) and is unassigned, and how `phone` triggers contact linking.

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 verb+resource, then two tight sentences on starting status and phone handling. 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 mutation tool with no output schema, the description covers the key non-obvious behaviors (default status, unassigned state, phone-to-contact linkage). It omits the custom_fields normalization/limit details, which the schema does carry.

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 60%, with the schema itself documenting `phone`, `agent_id` error cases, and `custom_fields`. The description reinforces the `phone` E.164 format and linking behavior, but adds nothing about `name`, `summary`, or the custom_fields limits, so it does not fully compensate for the coverage gap.

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

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

States a specific verb (Create) and resource (a lead), which is clearly distinguishable from siblings like update_lead or create_contact_note. It does not explicitly name an alternative to differentiate against, but the create/update split is self-evident from the name.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as update_lead, nor any stated prerequisites beyond the implicit need for an agent_id. The description describes post-conditions rather than when-to-use conditions.

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 non-obvious behavior: 404 agent_not_found for another company's, unknown, or deleted-on-list agents, and 403 agent_not_authorized for an agent of your company off the key's list. That is genuinely useful error semantics beyond the annotations.

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

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

Front-loads the resource and the payload difference from the list endpoint, then appends error semantics. Efficient and nothing is padded, though the error paragraph repeats almost verbatim what the schema's agent_id description already says.

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 with no output schema, the description does state what the response contains (settings, Main Instructions, AI handoff) and documents the failure modes, which is what an agent needs. The near-duplication with the schema's parameter description keeps it from being fully additive.

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 agent_id parameter is already documented with the same 404/403 semantics, so the description adds no meaning beyond the schema. Baseline 3 is correct when the schema fully documents the parameter.

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 and explicitly contrasts with the sibling list_agents by saying it returns the Main Instructions and AI handoff 'besides the basic details the list returns'. That differentiates it from the list tool, though it leaves the agent_id-keyed read versus update_agent/get_agent_analytics distinction to inference.

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 rather than stated: the agent is scoped to 'this key can act on', which is useful context, but there is no explicit when-to-use or when-to-prefer-list_agents guidance. The error conditions (404/403) inform access scope but are not selection 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 establish the safe read profile (readOnlyHint, idempotentHint, non-destructive), and the description adds substantial non-obvious behavior: a hard 92-day window, today's row continuing to count, zero-filled days without activity, failed counts that are never retried, and metrics that read zero before analytics recording began. These are exactly the operational caveats an agent needs and cannot get from 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?

The window definition, metric list, and caveats are front-loaded in a dense, well-ordered block, and every clause carries information. It loses a point for restating the title verbatim as the opening line and for a long trailing run of caveats that could 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?

With no output schema, the description carries the return-value burden and does so by enumerating the per-day metrics (new conversations, messages, customer mood, escalated/angry conversations, completed actions) plus window totals, along with zero-fill and recording semantics. Nothing an agent needs to call or interpret the result 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%, so the baseline is 3, but the description goes beyond the schema by bounding both dates ('at most 92 days', 'neither date can be later than today') and stating 'both included' inclusivity semantics. It also cross-references the error behavior for agent_id indirectly through the daily-report framing, though the schema itself carries the 404/403 detail.

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

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

States a specific verb (get) and resource (an agent's daily analytics) and immediately defines the shape of the returned data: per-UTC-day rows from `from` to `to` with named metrics. This clearly distinguishes it from siblings like get_agent, get_usage, and list_usage_history, which cover entity data and usage metering rather than conversation analytics.

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 rather than stated: the 92-day cap, the `to` default, and the note that reading analytics costs no messages hint at when it is appropriate to call. However, it never names an alternative (e.g. get_usage or list_usage_history) or gives an explicit when-not-to-use condition, so the 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds value beyond that by enumerating the returned fields, including the agent's reply and the moderation state (hidden vs shown) — meaningful since there is no output schema to carry that. It does not mention pagination or caching characteristics, but none are relevant to a single-entity fetch.

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

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

Two sentences, zero filler. The what-is-returned content is front-loaded and the id-sourcing hint closes it. Every clause earns its place.

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

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

For a simple two-parameter read with full schema coverage, the description supplies the one missing piece an agent needs — the shape of the result, since no output schema exists — and points to where the id comes from. Nothing required to call it correctly is absent.

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%: agent_id documents the 404/403 authorization semantics and comment_id documents the cross-agent 404. The description adds nothing new about parameter format or constraints, 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 ('Get one ... comment') plus the exact resource scope (Facebook or Instagram comment on an agent's page) and enumerates what is returned: text, author, post, agent's reply, moderation state. It is trivially distinguishable from list_comments and from hide_comment/unhide_comment 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?

Explicitly routes the agent to the sibling that supplies the required identifier: 'Get its id from list_comments.' That is a concrete workflow instruction. It stops short of stating exclusions or what to do when the comment does not exist (though the schema covers the 404), so it is clear context without full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and idempotency profile is fully covered by structured data. The description adds only the field list, with no further behavioral context such as error surface or result limits; the 404/403 semantics live in the schema, not the description.

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

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

Two sentences, zero filler, and the core purpose is front-loaded ahead of the id-provenance hint. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned fields (name, mobile, email, WhatsApp, social ids, status, custom fields) so the agent knows what it gets back. It does not describe field types or handling of absent values, which is a minor gap for a single-record get.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-schema value by naming the two upstream sources for contact_id (list_contacts, a lead's contact_id). It says nothing additional about agent_id beyond what the schema already documents.

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

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

States a specific verb and resource ('Get one contact of an agent') and enumerates the returned fields, which implicitly distinguishes it from the singular/plural sibling list_contacts. An agent can tell this fetches exactly one contact rather than a collection 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?

Explicitly tells the agent how to obtain the required contact_id ('from list_contacts or from a lead's contact_id'), which is real routing guidance to two sibling tools. It stops short of stating when NOT to use this tool (e.g. bulk retrieval) or any prerequisite beyond the id source.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the description's job is lighter. It adds genuine value by disclosing return content and the non-obvious AI behavior (ai_paused_until while a teammate's reply pauses it), which the structured fields do not 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 core action, then a dense but purposeful enumeration of returned fields, capped by a short routing sentence. Every clause maps to a distinct field or usage cue, 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?

There is no output schema, so the description appropriately carries the burden of describing what is returned, and it does so comprehensively. Combined with readOnly annotations and a fully covered input schema, an agent has what it needs 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 description coverage is 100%, so both parameters are fully documented in the schema (including 404/403 error semantics), making the baseline 3. The description only incidentally relates to conversation_id via the list_conversations routing hint and adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Get one conversation of an agent') and then enumerates the fields it returns, which distinguishes it from siblings like get_conversation_message and list_conversations. It does not explicitly name a sibling it is not, 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 closing line 'Get its id from list_conversations' gives an actionable prerequisite that routes the agent to the right sibling for obtaining the id. There are no explicit when-not-to-use conditions or exclusions, so it is clear context rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds that the message is returned as the conversation list shows it and that delivery status can be followed, which is useful context, but it does not disclose return shape, pagination, or authentication nuances beyond what annotations and schema descriptions already provide.

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

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

The description is short and front-loads the essential purpose. It is efficient overall, though the opening 'Get a message' is somewhat redundant with the title and the phrase 'as the list shows it' could be clearer.

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 low-complexity read tool with strong annotation coverage and a fully described input schema, the description supplies adequate context: it identifies the single-message scope and mentions the delivery status use case. No output schema exists, but the description still communicates enough for an agent 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 description coverage is 100%, so all three parameters are fully documented in the schema itself. The description adds no additional parameter-level detail, making the baseline score of 3 appropriate.

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

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

The description specifies the verb (Get/Read) and the resource (one message of the conversation), and its wording distinguishes it from list-level siblings by emphasizing retrieval of a single message. However, it does not explicitly name or contrast with the closest sibling, list_conversation_messages, so it falls short of a 5.

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

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

The description gives a clear use case: re-read a reply to follow its delivery status. It provides context for when this tool is useful, though it does not state exclusions or compare alternatives like list_conversation_messages or get_conversation.

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 genuine domain context about the semantics of the returned settings (three steps, counted from the AI's unanswered last reply, content drawn from the agent's knowledge), but says nothing about return format or failure behavior beyond what the schema already documents.

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 one-line summary is front-loaded and the elaboration follows in a single informative sentence. It is slightly dense but no sentence is wasted.

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

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

For a simple read tool with full parameter documentation and complete annotations, and with no output schema to compensate for, the description supplies enough domain meaning about what the settings contain. The only real gap is the absence of when-to-use routing, which is minor here.

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

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

Schema description coverage is 100% and the single agent_id parameter is fully documented in the schema, including the 404 agent_not_found and 403 agent_not_authorized outcomes. The description adds no parameter-level information, 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 (get) and resource (an agent's follow-up settings), and the second sentence concretely describes what those settings govern: whether the AI follows up, on which platforms, and timing across up to three steps. It does not explicitly name the sibling update_follow_up_settings, but the read/update split is unambiguous from the name.

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 explains what the settings are but never says when to call this tool versus alternatives, nor any prerequisites. The only usage signal is the implicit get-vs-update pairing with update_follow_up_settings, which the reader must infer.

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 readOnly, idempotent and non-destructive semantics, so the bar is lower. The description still adds value by disclosing the response payload ('full text content') versus the lighter list output, information not present in 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?

Two compact sentences, front-loaded with the payload description and followed by the sourcing hint. No redundant restatement of the title or name.

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

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

With no output schema, the description correctly fills the gap by naming the returned content, and the schema carries parameter error behavior. It is nearly complete for a simple two-parameter read, though it says nothing about auth requirements beyond what the schema states.

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

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

Schema description coverage is 100%, so both agent_id and knowledge_base_id are documented with error semantics in the schema itself (404/403 cases). The description only adds the provenance hint for knowledge_base_id and nothing about agent_id, so baseline 3 is warranted.

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

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

States a specific verb ('Get') and resource ('one knowledge base of an agent') plus the payload scope ('including its full text content'), which cleanly separates it from the sibling list_knowledge_bases. The parenthetical contrast makes the boundary explicit.

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

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

Gives concrete prerequisites ('Get its id from list_knowledge_bases') and via the parenthetical makes clear when to prefer the list tool instead. It stops short of naming the other retrieval/update siblings (replace_knowledge_base), so it is clear context rather than a full when/when-not matrix.

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. With no output schema, the description adds real value by disclosing the returned fields (name, phone, status, AI summary, custom fields, assignee, pinned, contact_id, conversation_id). Auth/error behavior (404 not_found, 403) lives only in the schema, not the description.

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

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

Two tight sentences with no filler: the purpose and returned-field inventory come first, and the id-sourcing instruction is placed last where it is needed. The field list is long but earns its place because no output schema exists.

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 read tool with annotations covering safety and the schema covering errors, the description closes the only real gap by listing the returned fields in the absence of an output schema. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both required parameters are fully documented in the schema, including the cross-agent 404 behavior. The description only implies the lead_id origin by pointing at list_leads and adds no format or scoping detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one lead of an agent') and then enumerates exactly what is retrieved, so the agent knows the shape of the result without opening a schema. The closing pointer to list_leads as the source of the id cleanly separates it from list-family 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?

It tells the agent where the required lead_id comes from ('Get the lead's id from list_leads'), which is the key precondition for calling it. It gives no explicit when-not-to-use guidance (e.g. versus list_leads for bulk retrieval), so it falls short of a full 5.

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

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

Annotations already declare a safe read (readOnlyHint, idempotentHint, closed-world), and the description layers on real behavioral context not present in structured fields: the prompt is the same text edited under Clients → ⋮ → AI Instructions, only the prompt is returned regardless of on/off state, and the missing-tool case is a 404. These are precisely the extra traits this dimension rewards.

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 scope are front-loaded in the opening lines before the dashboard aside and error codes. Every sentence carries information, though the leading line duplicates the tool title and the dashboard-editing detail is slightly parenthetical.

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-only getter with no output schema and annotations covering safety, the description supplies what the value is, its scope, availability, and the error case. The only omission is the response field shape, which is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100% and the single agent_id parameter already documents the uuid format plus the 404 agent_not_found and 403 agent_not_authorized cases. The description adds no new parameter meaning, 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?

Specific verb+resource ('Get the lead capture prompt') followed by a precise scoping clause: it returns the instruction the built-in Capture Lead tool follows, not the tool's other settings. That boundary ('Only the prompt: the tool's other settings stay in the dashboard') cleanly separates it from the sibling update_lead_capture and from get_follow_up_settings.

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 usable context clearly: the value is returned whether the tool is on or off, and an agent lacking the tool yields 404 lead_capture_not_found. It never explicitly says when to prefer this over get_agent or update_lead_capture, 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?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuine behavioral context beyond them: any valid key works regardless of scopes, and the secret itself is never returned (only prefix and last_four). That is useful auth and output-shape disclosure not found in the structured fields.

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

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

Front-loaded with the purpose, then scope/usage, then the return-fragment note. Every sentence carries information, though the opening line duplicates the title and the prose is slightly sprawling for a no-arg tool.

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

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

For a zero-parameter, no-output-schema tool whose safety profile is already in annotations, the description covers what the agent cannot infer: returnable fields, that the raw key is withheld, and the permission-free access model. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to compensate for, and it correctly avoids inventing parameter detail.

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

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

States a specific verb ('describe') and resource ('the calling key') and then enumerates exactly what comes back: name, scopes, agent list, owning company, and rate limit. This clearly distinguishes it from siblings like get_agent or get_usage, so an agent can pick it without opening the schema.

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

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

Explicitly states the trigger: 'Any valid key may call it... so it is the first call to make: to check a key works and see what it can reach.' This gives an unambiguous when-to-use condition (connectivity/scope verification) rather than leaving usage 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?

Goes well beyond the annotations: it discloses a negative guarantee ("never returns prices or payment details") and enumerates the two 409 failure modes with their exact codes and the conditions that trigger them, including the no-subscription-at-all case. The read-only/idempotent hints are already in annotations, but the error contract is genuinely additive.

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

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

Front-loaded with the purpose in the first line, then scoping and error detail. The opening sentence duplicates the title verbatim, which is mild waste, and the error clause is dense prose, but no sentence is off-topic.

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 annotations already covering the safety profile, the description carries the remaining burden well: it describes what the payload contains, what it deliberately excludes, its scope, and every documented failure path. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter behavior is asserted in a way that could conflict 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?

States a specific resource set (organization plan, subscription status, current billing period, message/agent usage against limits), so an agent knows exactly what is returned. However, it never names or contrasts with the sibling list_usage_history, so the current-vs-historical distinction must be inferred.

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?

Scope guidance is present ("company-wide, whatever the key's agent list"), which implies this is the org-level snapshot rather than a key-scoped read. But there is no explicit when-to-use versus list_usage_history or any stated prerequisite, so routing 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 and non-destructive. The description adds real value beyond them by disclosing the visibility scoping rule (a key limited to some agents sees only its own sends) and the exact error shape (404 message_not_found for another agent's message).

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

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

Front-loaded and short, with the scoping caveat placed where it matters. The first sentence duplicates the title verbatim, which is mild waste, and the awkward mid-sentence line break slightly hurts readability.

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 main ambiguity an agent faces (cross-agent visibility and the 404 result) is covered. It does not describe the possible status values returned, which is the only notable gap given there is no output schema.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented as 'the id returned from a previous send.' The description's phrasing ('by the id the send returned') only restates the schema rather than adding format or constraint detail, 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: look up the delivery status of a message previously sent via sendWhatsAppMessage or sendWhatsAppTemplate. The tie to those specific send tools separates it from generic message readers like get_conversation_message, though it never explicitly names that sibling to draw the contrast.

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 context: use it with the `id` a prior send returned, after calling one of the two named send tools. It does not offer explicit alternatives or when-not-to-use guidance, but the triggering workflow is unambiguous.

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

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

Goes well beyond the annotations: it discloses that the comment is not deleted, that the commenter and friends still see it on Facebook, the resulting moderation.hidden_by value ('user' vs 'platform'), that hidden comments receive no reply, and specific failure modes (422 comment_already_hidden, 422 platform_hide_failed with transient retry guidance, and 500-then-already_hidden meaning the write succeeded). This is exactly the behavioral context annotations can't 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?

Front-loads the core action and platform scope before the behavioral and error detail, and every sentence carries information. The opening line restating the title is mildly redundant, which keeps it short of a 5.

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

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

For a mutation tool with no output schema, the description supplies the side effects, state transitions, error taxonomy, and retry semantics an agent needs. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so agent_id and comment_id are fully documented in the schema; the description adds no further parameter meaning. Baseline 3 applies when the schema does all the heavy lifting.

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

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

States a specific verb+resource ('Hide a comment') and pins the target platforms ('Facebook or Instagram') plus the analogy to teammate behavior on the Comments page. An agent can distinguish this from siblings like unhide_comment purely from the text.

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 conveys the semantic effect (leaves public view but isn't deleted), which implies reversal via unhide_comment, but it never explicitly states when to use this tool versus restoring visibility or taking other moderation actions. Usage is inferred rather than directed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces that with 'Read-only: your team is managed in the dashboard' plus ordering ('earliest to join first') and the eligibility semantics of can_open_agent. It adds real behavioral context beyond the annotations, though it says nothing about result size or pagination.

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 each sentence carries information (ordering, eligibility, ID-resolution rationale, read-only note). The opening line duplicates the title verbatim, which costs a little, but nothing is padded.

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

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

With no output schema, the description does the work of explaining the return shape: ordering, the can_open_agent flag, and the user_id-to-name resolution use case. Coverage of the remaining returned fields and result size is left implicit, so it is not fully complete.

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

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

Schema description coverage is 100%, and the single agent_id parameter already documents the 404/403 failure modes in detail. The description adds no parameter-level syntax or format information, so the baseline 3 for schema-driven coverage 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?

Specific verb+resource ('List teammates for an agent') and it disambiguates scope by naming the returned eligibility flag. It doesn't explicitly differentiate from the sibling list_organization_members, which is the closest alternative, 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?

Gives concrete context for when this is useful: resolving a teammate's user_id seen on a lead (assigned_to) or note (author_id) back to a name. It also notes people who cannot open the agent are still returned, which prevents misuse. No explicit alternative tool is named, so not 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 cover read-only, idempotent and non-destructive behavior, so the bar is lower. The description still adds real context beyond them: ordering ("newest first"), that deleted agents are excluded, and the key-based scoping. These are concrete traits an agent cannot infer from the annotations alone.

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

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

Three tight sentences with the scoping constraint front-loaded and no filler. The opening line merely repeats the title verbatim, which is slight redundancy, but the remaining content is efficient.

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

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

No output schema exists, so the description usefully covers return characteristics: the `id` field maps to the `agentId` used by agent endpoints, ordering, and deleted-agent exclusion. It does not mention pagination or result limits, which is the only notable gap for a list 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 the baseline is 4. There is nothing to document, and the description correctly adds no parameter claims it cannot support.

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

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

States a specific verb ("List") and resource ("agents") plus a precise scope ("this key can act on"). This cleanly separates it from siblings like get_agent (single agent) and list_agent_members (members within an agent) 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?

The description clarifies the result scope ("every agent, or only those on the key's agent list") but never states when to prefer this over get_agent or list_agent_members. Usage is implied by the verb rather than explicitly guided, and there are no exclusions.

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

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

Annotations already cover the read-only, idempotent, closed-world profile, so the bar is lower; the description still adds ordering ('newest first'), return shape (reply under each comment, moderation attached), exclusion of disconnected/moved pages, and the non-obvious caveat that moderation lives in `moderation`, not the reply's `status`. That last point is a genuine behavioral clarification not present in structured fields.

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

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

Dense and front-loaded: scope, ordering, exclusions, then filters. The opening line repeats the title verbatim, which is minor waste, but the remaining sentences each carry 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 carries return-shape burden and does so adequately (reply nested under each comment, moderation field semantics, ordering). Pagination and error codes are handled in the schema. Slightly thin on what other fields a comment record contains, but sufficient to call 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 83%, so the baseline is 3, but the description goes further by explaining what the moderation_status values actually select ('hidden' lists everything hidden now by AI, teammate or platform; 'kept' lists what the AI checked and left visible) — meaning the enum alone does not convey. platform and post_id are also described in prose.

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 an agent's comments') and immediately narrows scope: Facebook/Instagram comments on the agent's connected pages, newest first, with the reply and its moderation. This distinguishes it from siblings like get_comment (single item) and hide_comment/unhide_comment (mutations).

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 concrete filtering guidance for moderation_status, platform and post_id, and explains the semantics of the two filter values ('hidden' vs 'kept'), plus an exclusion rule (comments of disconnected or moved pages are omitted). It stops short of explicitly contrasting with get_comment or stating when not to use it, so it is clear context rather than full when/when-not routing.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description adds useful context beyond that: it discloses the scope of results (active and not active), what each entry reports (AI answers messages/comments), and an auth prerequisite ('needs Meta's login') for the related dashboard operations.

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 title line is repeated as the first sentence, which is slightly redundant, but the payload sentence is dense with relevant detail and the dashboard caveat is front-loaded at the end. No filler beyond the echoed title.

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

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

With no output schema, the description correctly compensates by describing what the list contains (channel types, active state, AI-answering flags). The auth note covers a related workflow, though pagination/ordering behavior is 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 description coverage is 100% and the single agent_id parameter already documents its UUID format and its 404/403 error semantics in the schema. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('list an agent's connections') and then enumerates exactly what a connection is (Facebook pages, Instagram accounts, WhatsApp numbers), including the active/inactive dimension and the AI-answering flag. An agent can distinguish this read operation from connect/disconnect actions without opening the schema.

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

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

The description implicitly frames usage by noting that connecting and disconnecting happen in the dashboard rather than via this tool, which is a partial when-not statement. However, it never names or contrasts a sibling (e.g. update_connection, list_agents), so the agent must infer that this is the read-only viewer for an agent's channels.

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 closed-world scope, so the safety profile is covered. The description adds genuine context beyond that: results are ordered 'newest first' and the timeline blends two distinct record types, with `status_change` entries flagged as system-generated/read-only. It does not, however, mention pagination behavior in prose.

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 every clause carries content (ordering, record types). The opening line duplicates the title verbatim, which is a minor redundancy rather than a flaw.

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

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

For a read-only list tool with no output schema, the description supplies the ordering and the composition of returned entries, which is what an agent most needs. It stops short of describing the shape of individual items (fields per note type) or pagination limits, but the annotations and schema cover the remaining risk.

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, cursor, agent_id and contact_id (including clamping, cursor semantics and 404/403 error mappings) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('a contact's notes'), and further defines what the resource contains: `user_note` entries written by people and `status_change` entries Mojeeb generates. This clearly separates it from create_contact_note and update_contact_note without needing to open any schema.

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

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

Usage is implied by the name and the description's framing as a timeline read, but there is no explicit when-to-use or when-not guidance, nor any pointer to alternatives such as get_contact (contact fields) versus this timeline view. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: results are ordered newest first and contacts are auto-created from incoming messages and new leads, explaining why no create path exists — a trait not expressed in the structured fields.

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

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

Short and front-loaded: identity first, then ordering, then the auto-creation caveat. The opening line duplicates the title verbatim, which is the only wasted text.

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

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

With no output schema, the description supplies the one return-shape fact an agent needs (newest first) while the schema handles all filter and pagination semantics. Nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so limit, cursor, search, channel, date_from and date_to are already fully documented in the schema, including clamping and error behavior. The description adds no parameter-level meaning, 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 (list an agent's contacts) and frames the entity as 'the people behind the agent's conversations and leads, newest first'. The note that there is no create endpoint cleanly separates it from creation-side siblings like create_lead, though it never explicitly contrasts with get_contact or list_leads.

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 rather than stated: the agent learns it can only read contacts that Mojeeb auto-generates, but there is no explicit guidance on when to prefer list_contacts over get_contact, list_leads, or list_contact_notes, and no when-not conditions. Adequate but with clear routing gaps.

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), and the description adds genuinely non-obvious behavior: ~24h signed attachment links, platform-timestamp ordering that can skip messages, and an explicit untrusted-input/prompt-injection warning on customer-written text. None of this is derivable from 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?

Front-loaded with the core modes before the caveats, and every sentence carries information. It is dense and slightly long, and the opening line merely restates the title, 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 output schema, the description still discloses the return-relevant concepts an agent needs (`next_cursor`, `has_more`, message `id`, attachment links) plus ordering guarantees and error-adjacent pitfalls. Nothing needed 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 description coverage is 100% so baseline is 3, but the description adds substantial meaning beyond it: the interaction and mutual exclusivity of `after` vs `cursor`, the ordering each produces, and the practical consequence of using `after` with your newest message id.

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

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

States a specific verb+resource ("List a conversation's messages") and immediately clarifies scope via the two read modes, so an agent knows it returns a message collection scoped to one conversation. It does not explicitly name the sibling it differs from (e.g. get_conversation_message for a single message), so differentiation is implied by the verb 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?

Explicitly contrasts the two modes ("Without `after` ... With `after` ... Not both"), states the condition for each, and gives a concrete catch-up loop ("call again with `after` set to the last message you got while `has_more` is true"). It also warns when the obvious approach fails and prescribes the workaround.

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 and closed-world, and the description still adds substantial behavior: ordering rules, the fact that status/read/flag/assignee changes do not refresh `last_message_at`, platform-timestamp skew, caption-less media not counting, deleted conversations never appearing, and `422 invalid_request` for a bogus cursor.

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?

Long and dense, but front-loaded with purpose and the polling workflow before edge cases, and nearly every clause carries operational meaning (timestamp skew, caption-less messages, window rules). It leans on heavy parentheticals and a single sprawling paragraph rather than headings, which slightly hurts scannability.

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 covers the return shape itself (last message, author, timestamp, read state, attention flags, AI state, assignee), plus pagination, dedupe and error behavior. For a 12-parameter read tool this is as complete as the format allows.

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% and several undescribed params (status, is_read, contact_id) get no individual explanation. However, the description adds real semantics beyond the schema: that filters without `active_since`/`contact_id` are bounded to 90 days, that `active_since` follows `last_message_at` only, and that `search` is limited to name and last message.

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

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

Opens with a specific verb+resource ("List an agent's conversations") and goes on to define exact scope: most recently active first, removed/empty conversations excluded, and what each item carries. It also distinguishes itself from siblings by naming `getConversation` for message-less conversations and clarifying that `search` never reaches inside message history.

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

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

Gives an explicit polling recipe (set `active_since` a few minutes before the newest `last_message_at`, page while `has_more`, dedupe by `id`) and states exactly when to reach for `getConversation`. It also explains the default 90-day window for filtered lists and the condition (sending `active_since`) that lifts it.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful facts beyond that: results are ordered newest first, what each record contains (outcome, duration, conversation), and an explicit redaction guarantee that request/response payloads are never returned.

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

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

Two short sentences, front-loaded with the ordering and content summary before the exclusion note. The first line only restates the title, which is mild redundancy, but the rest is dense with signal and 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 carries the burden of describing returns and does so in outline (outcome, duration, conversation, newest first) plus a clear statement of what is withheld. Pagination and error behavior live in the schema, so the remaining gap is minor.

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

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

Schema description coverage is 100% and each parameter (limit, cursor, status, tool_id, agent_id) is documented in the schema with clamping, cursor reuse and 404/403 error semantics. The description adds nothing parameter-specific, so the baseline of 3 applies.

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

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

States a specific verb and resource (list runs of a custom API tool) and immediately disambiguates the otherwise vague word 'runs' as 'the times the AI used the tool'. It distinguishes itself in substance from list_custom_api_tools (tools themselves vs. their executions), though it never names that sibling 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 description gives no when-to-use or when-not guidance and names no alternative. An agent must infer from the noun phrase alone that this is for inspecting execution history rather than tool configuration; nothing routes it against list_custom_api_tools or get_agent_analytics.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds two useful behavioral facts: results come back 'oldest first', and each item exposes its site's login but with the login's secrets stripped. That redaction detail is exactly the kind of context annotations cannot convey.

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

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

Three short lines, with the ordering and login-redaction details front-loaded rather than buried. The first line is a verbatim restatement of the title and earns nothing, but the remaining two lines are dense and waste-free.

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 list tool with no output schema, the description is adequate: it discloses result ordering and part of the item payload (login without secrets). It says nothing about pagination, result limits, or whether an empty list is possible, which matters for a tool whose return shape has no 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?

Schema description coverage is 100% and the single agent_id parameter is documented in the schema with its 404/403 failure modes. The description contributes nothing about the parameter, so the baseline of 3 is appropriate.

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

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

States a specific verb (List) and resource (an agent's custom API tools), and the second line clarifies what these tools represent ('what its AI can do with your own system'). It is clear, though it never explicitly distinguishes itself from the close sibling list_custom_api_tool_runs, leaving the agent to infer 'tools' vs 'runs'.

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 states when to use this tool versus alternatives, nor any preconditions. With roughly a dozen list_* siblings in scope, the absence of any routing guidance is a real gap beyond a mere implied 'use this to list things.'

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

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

Annotations already carry readOnly/idempotent/non-destructive/closed-world. The description adds genuinely new information the annotations do not: the result excludes knowledge base content, which manages the agent's expectation about output shape without an output schema.

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

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

Two sentences, both front-loaded: the operation first, then the scoping caveat and the redirect to the sibling. No filler.

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

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

For a single-param list with an output null-schema situation and full annotation coverage, the description covers purpose, scope, and output limitation. It omits pagination/ordering behavior, a minor 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 the agent_id description already documents the 404/403 failure modes in detail. The description adds nothing about the parameter, so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (an agent's knowledge bases) with explicit scope: 'Every knowledge base linked to the agent'. The parenthetical '(get one to read it)' distinguishes it from get_knowledge_base, so an agent can route correctly without opening either schema.

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

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

The parenthetical explicitly names the alternative (get one) and the condition that selects it (need to read content). It lacks an explicit statement of when-not to use it (e.g., no agent_id) but the list-vs-get split is clear.

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

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

Annotations already declare a safe read (readOnlyHint, idempotent, non-destructive), and the description adds substantial behaviour the annotations cannot: the default statuses used when no status field exists, that built-in fields are immutable via the API, how writable built-ins map to other operations (assignLead, listContactNotes), and the warning that custom_fields are not validated against this list.

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

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

The purpose is front-loaded and every clause carries real information (default statuses, built_in semantics, writable-property mapping, validation caveat). It is dense, near-reference-material length for a simple list tool, which slightly hurts scannability but not correctness.

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

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

With no output schema, the description carries the return-value burden and does so: it explains that the field keyed 'status' exposes options, the default fallback statuses, and the built_in flag meaning. Combined with annotations covering safety, an agent has everything needed to call and interpret 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?

There is a single agent_id parameter and the schema description coverage is 100%, with the schema itself documenting the 404/403 error behaviour. The description adds nothing further about parameters, so the baseline 3 for schema-carried semantics applies.

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

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

States a specific verb and resource ('List the agent's lead fields') and immediately scopes it as the lead form in display order, which is the field schema rather than lead records. This clearly separates it from siblings like list_leads and get_lead.

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

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

Implied usage is clear: the keys of non-built-in fields are 'what custom_fields is for,' so an agent knows to read this before writing custom field values, and it warns to validate before writing because the API doesn't check. It stops short of naming an explicit alternative or a when-not-to-use condition.

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 and non-destructive, so the bar is lower, yet the description still adds substantial non-obvious behavior: pinned leads sort first on page one only, later pages never contain them, pin overflow beyond `limit` is silently not returned, and the sent filters combine with AND. This ordering and exclusion semantics is exactly the kind of trait an agent cannot infer from structured fields.

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

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

Two tight paragraphs, with the consequential pinned-lead caveat front-loaded ahead of the filter-combination rule. The only waste is the first line, which restates the title rather than advancing the description.

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

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

For a 9-parameter list tool with full schema coverage and no output schema, the description covers the tricky operational semantics (pagination, pinning, filter conjunction). It leaves the shape of a returned lead undescribed, which is the main remaining gap given there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: the enumerated filters (status, search, creation dates, assignee, custom fields) combine conjunctively rather than unioning. The `limit` up-to-100 note merely repeats the schema's maximum.

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 phrase, 'List an agent's leads', which mirrors the title and makes the plural/list scope distinct from the sibling get_lead. It does not explicitly name alternatives like get_lead or list_lead_fields, 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?

It gives an actionable invocation rule — set `limit` above the number of pinned leads to avoid silently dropping them — which is real usage guidance. However, there is no when-to-use-this-vs-siblings guidance (e.g. get_lead for a single lead, list_lead_fields for status/field keys), leaving the routing 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 cover safety, yet the description adds real behavioral detail beyond them: ordering (earliest to join first), key-scoped visibility ('a key limited to some agents sees only those agents in agent_ids'), the all_agents vs agent_ids distinction, and the exclusion of pending invitations. This is meaningful context an agent cannot get from the structured fields.

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

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

Front-loaded with the verb+resource, then dense supporting detail. Four sentences that mostly earn their place, though the field-by-field enumeration and the visibility rule could be marginally 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?

With no params, no output schema, and annotations carrying the safety profile, the description supplies everything an agent needs: what is returned, in what order, what is excluded, and how key scoping limits visibility. Nothing essential is missing.

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

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

Zero parameters, so the baseline is 4. The description usefully explains response fields (all_agents/agent_ids, role, email) which the empty input schema cannot, adding value even though there are no params to document.

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

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

States a precise verb+resource ('List your organization's members') and enumerates the returned fields (role, email, agents). The word 'organization' implicitly distinguishes it from the sibling list_agent_members, though the sibling is never named, so the differentiation is inferable rather than explicit.

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

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

The closing 'Read-only: your team is managed in the dashboard' hints at when to use this (inspection only, edits happen elsewhere), but there is no explicit when-to-use versus alternatives guidance or reference to list_agent_members. Usage is only implied.

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

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

Annotations already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds real domain behavior beyond the annotations: ordering (newest first), the meaning of the `current` marker, and the non-obvious rule that history restarts after cancellation when the free plan opens a new subscription. It omits any note on pagination or result size limits.

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

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

Effectively two sentences, front-loaded with the core purpose before the clarifying detail. The only waste is that the first line repeats the title verbatim, which buys the agent nothing. The 'history starts again after a cancellation' sentence earns its place by explaining a surprising data shape.

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-argument, read-only listing tool with no output schema, the description is nearly sufficient: it characterizes the records, their order, and the `current` marker so the agent can interpret results without a schema. The missing pieces are pagination behavior and any contrast with get_usage, which is the one thing an agent most needs in this sibling set.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is empty with additionalProperties=false, matching the description's implication that all filtering is 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?

The description states a specific verb+resource ('List usage by billing period') and enriches it with scope details: every billing period of the current subscription, newest first, with messages used against each period's limits. It is clear what the tool returns, but it never distinguishes itself from the sibling get_usage, leaving the agent to guess which usage tool to pick.

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

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

Usage is only implied: it is a historical listing of billing periods, so an agent can infer it is for time-series/billing-period inspection. There is no explicit when-to-use, no exclusions, and critically no guidance on when to prefer this over the sibling get_usage, so the routing decision 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on substantial behavior the annotations cannot express: a 10 req/min per-key rate limit counted separately from other calls, caching advice, and precise failure semantics — 404 not_found for a non-WhatsApp connection, 409 connection_inactive, 409 connection_needs_reconnection (retry won't help), and 503 meta_unavailable with retry-with-backoff. It also explains the per-item payload shape for building a later POST.

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

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

Front-loaded and dense with useful detail — scope first, then payload shape, then rate limit, then error taxonomy. The only waste is the opening line, which merely restates the tool title verbatim before the real content begins.

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

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

No output schema exists, and the description compensates by describing the return contents in detail: one item per language version, sorted, up to 100 items, each carrying body/header parameter keys in order, header format, and button index/value field. Combined with the complete error taxonomy, nothing needed to call it correctly is missing.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is a 3. The description adds meaning beyond the schema by tying `connection_id` to the concept of 'one of the agent's WhatsApp numbers' and by restating the 404 case for a connection that isn't a WhatsApp number in the tool's own semantic frame.

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 every template of one of the agent's WhatsApp numbers), plus scope details that separate it from siblings: live read from Meta, one item per language version, sorted by name then language, capped at 100. An agent can distinguish it from send_whatsapp_template or get_whatsapp_message_status without opening any schema.

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

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

Gives clear operational context: templates are read live from Meta, so 'keep the list, and read it again after your templates change,' and only `approved` templates can be sent (implying send_whatsapp_template is the routing target). It does not explicitly name any sibling tool as an alternative, so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: a KB can be shared across multiple agents, the change propagates to all of them, and it is refused with a specific 403 shared_with_other_agents unless the key can act on every consuming agent. That is meaningful disclosure beyond structured fields.

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

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

Front-loaded with the core semantics before the sharing/error caveat. The opening restates the title verbatim, which is mildly redundant, but the body is dense and earns its sentences.

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

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

For a destructive, no-output-schema mutation tool with 5 params, the description covers the overwrite scope, the cross-agent propagation risk, and the 403 refusal condition. It does not state the return shape, but with no output schema that gap is minor.

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

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

Schema coverage is 60%, and the description compensates by clarifying the tags parameter's conditional behavior ('changes only when sent') and the overwrite semantics of name/content. The rich content and agent/knowledge_base_id error semantics live in the schema, so the description adds value mainly for tags and replacement scope.

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 (replace) and resource (knowledge base) and clarifies the exact semantics: name and content are overwritten, tags only when sent. This distinguishes it from create_knowledge_base and get_knowledge_base, though the siblings are never 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?

The description implies when this applies (full replacement of an existing KB) via the tags rule, but gives no explicit when-to-use versus update/create guidance or prerequisites beyond the error conditions. Usage is inferable but not spelled out.

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

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

Beyond the annotations, it discloses two meaningful behaviors: the cancellation of the follow-up the pause scheduled, and that it is a no-op without a running pause (consistent with idempotentHint=true). It also clarifies a boundary ('doesn't switch on an AI that ai_enabled: false switched off'). This adds real value over the structured hints.

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

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

The action is front-loaded and each sentence earns its place by describing mechanism, effect, and boundaries. The leading repetition of the title is slightly redundant, but overall it is tight and well-ordered.

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 adequately covers the behavior an agent needs: the state change, the side effect on the scheduled follow-up, and the no-op case. No return values are needed, though it omits any note on what the call returns on success.

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 detailed error semantics for both agent_id and conversation_id, so the schema carries the parameter burden. The description adds no additional parameter meaning, which is the expected baseline when coverage is high.

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

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

The description states a specific action on a specific resource: ending a conversation's AI pause so the AI answers the next message. It is clearly distinguishable from siblings like update_conversation or get_agent, and the opening line names the exact resource (a conversation's AI pause).

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

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

It explains the triggering condition (teammate replies with ai_handoff_enabled on) and a when-not condition ('without a running pause it changes nothing'). It does not explicitly route to an alternative tool, but no obvious sibling performs this same action, so the context is sufficient.

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 (destructive/readOnly/openWorld/idempotent hints) by disclosing AI-handoff pausing behavior, the async send lifecycle (queued→sent/delivered/read/failed), idempotency-key refusal semantics including the 60s 409 idempotency_key_in_progress window, and 422 error conditions. This is exactly the mutation/auth/retry context the 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?

Front-loaded with the core action, and nearly every sentence earns its place with concrete behavioral detail. It is dense and runs as one long block rather than clearly sectioned, which slightly hurts scanability, but there is little filler.

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

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

For a no-output-schema mutation tool, the description is remarkably complete: error codes, retry guidance, async status tracking, AI-handoff interaction, and per-channel constraints are all covered. An agent has everything needed to invoke and follow up 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% and the schema already documents text length/splitting and the agent_id/conversation_id error cases in depth. The description adds no new parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Sends a text reply to the customer on the conversation's channel') and immediately differentiates from siblings by naming sendWhatsAppTemplate as the alternative when the WhatsApp window is closed. An agent can tell this apart from send_whatsapp_message and assign_conversation without opening any schema.

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

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

Gives explicit when-to-use (reply to a customer as your team), when-not (TikTok channel_not_supported; messaging_window_closed on WhatsApp/Facebook/Instagram), and named alternatives (sendWhatsAppTemplate, getConversationMessage for status). It also states what it does NOT do ('never assigns the conversation'), implicitly routing to assign_conversation.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds a genuinely important behavioral constraint the annotations do not convey: the message will be rejected outside Meta's 24-hour customer-service window.

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

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

Two sentences, zero filler, with the restriction and the fallback route front-loaded rather than buried.

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

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

No output schema exists, and the description need not explain return values. It covers the critical eligibility constraint and the fallback, though it says nothing about delivery failure/status checking, which get_whatsapp_message_status would help with.

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 75%, close to the high-coverage baseline, and the schema already documents E.164 formatting, the UUID agent_id, and the 1–4096 char body limit. The description contributes no additional parameter meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Send a free-form WhatsApp text message') and immediately scopes it against the templated alternative. An agent can distinguish it from send_whatsapp_template and send_conversation_message from the description alone.

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

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

Gives an explicit condition for use (customer messaged within the last 24 hours) and explicitly steers outside the window to the templates route. Minor deduction: it names the HTTP path `POST /v1/whatsapp/templates` rather than the sibling tool `send_whatsapp_template`, so the agent must infer the mapping.

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?

Far exceeds the annotations (which only say destructive/openWorld/non-idempotent): it explains the pre-send name/language check against the number's templates, the specific 422 error codes, the fact that the check accepts unapproved templates, and the conditions under which the check is skipped entirely (unreadable Meta templates, >100 templates), yielding a 202 whose verdict appears in status. This is exactly the kind of behavioral nuance the 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?

Purpose is front-loaded in the first sentence, followed by increasingly detailed caveats. Every sentence conveys substance (approval requirement, check behavior, failure modes), though the dense multi-clause sentences around the >100-template edge case read as 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?

For a complex, side-effecting tool with no output schema, the description covers the safety-critical behavior thoroughly: approval prerequisites, validation semantics, async 202 outcomes, and where the failure status surfaces. It stops short of stating what the immediate response returns (e.g. a message id), which would complete the picture.

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 75% and the nested schema is extremely detailed (headers, buttons, media limits, OTP aliases), so the schema carries the parameter burden. The description adds no per-parameter meaning of its own, 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 opening sentence states a specific verb (send) and resource (Meta-approved WhatsApp template), making the operation unambiguous. It does not name or contrast the sibling send_whatsapp_message / send_conversation_message, so an agent must infer that this is the template-only path, which keeps it just short of a 5.

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

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

Gives real context: templates can be sent at any time, including outside the 24-hour customer-service window, and points to listWhatsAppTemplates for status and required fields. It never explicitly says when to prefer this over the free-form send siblings, so the routing guidance is useful but incomplete.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substantial behavioral detail: moderation.status becomes unhidden, auto-hide will not hide it again, the AI reason is preserved, and specific error/retry semantics are documented. This goes well beyond the structured fields and is highly useful 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 front-loaded and each section (effect, errors, retry guidance) is relevant. However, it begins by repeating the title verbatim before elaborating, 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?

Given no output schema, the description covers the state change, side effects, error codes, and retry behavior thoroughly. An agent has enough information to invoke this tool correctly and interpret common outcomes.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides, 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?

States a specific verb and resource ('Show a hidden comment') and clarifies the platform scope ('on Facebook or Instagram'). The hidden-comment state and 'again' wording distinguish it from hide_comment and from generic comment retrieval tools.

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

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

The description gives clear context: use this to show a hidden comment again, and the 422 comment_not_hidden error implies the prerequisite that the comment must currently be hidden. It does not explicitly name alternatives like hide_comment or get_comment, so it falls short of a full when/when-not guide.

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 supply destructive/idempotent/openWorld hints; the description goes well beyond them by disclosing atomic validation ('Everything is validated before anything changes'), the full-replacement semantics of `instructions`, the propagation delay ('the AI follows the new text on its next replies, usually within a minute'), the no-op behavior when the text is unchanged, and the `422 field_not_writable` contract with the offending field in `param`. That is the behavioral detail a mutation tool needs.

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 correctly: field list first, then validation/replacement behavior, then rejection rules, then sibling routing. Individual sentences are clause-heavy and slightly run-on, but every clause carries operational information and there is no filler.

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

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

For an 8-parameter, no-output-schema mutation tool, the description supplies the missing pieces: error codes, atomicity, replacement semantics, propagation latency, and escape hatches to sibling tools. Nothing an agent needs to invoke this correctly is absent, and return formats are unnecessary given 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?

Schema coverage is 100%, so the baseline is 3 and the per-field mechanics (IANA format, clearing via empty string, length bounds) are already handled by the schema. The description earns the bump by explaining whole-text replacement for `instructions`, the no-op re-send case, and the fact that certain fields are rejected wholesale — semantics the schema's `additionalProperties: false` does not itself convey.

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

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

Specific verb+resource (update an agent's settings) followed immediately by an exhaustive enumeration of the mutable surface: name, description, instructions, time zone, AI handoff, comment auto-hide. It also explicitly carves out what is *not* this tool — deletion lives in the dashboard, follow-ups in `updateFollowUpSettings`, per-channel AI switch in `updateConnection` — so the agent can separate it from every nearby sibling.

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

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

States the precondition plainly ('Send at least one (`422 no_settings` otherwise)') and names the replacement tools for the adjacent concerns, which is exactly the when/when-not/alternative guidance an agent needs. The non-writable field list ('status', 'ai_model', 'model_provider', 'avatar_url', 'language') doubles as a do-not-attempt directive with the resulting error code.

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 say destructive/idempotent/not-read-only. The description goes far beyond: messages off still delivers to the dashboard and lets scheduled follow-ups fire; comments off means comments are neither answered nor recorded and re-enabling does not backfill them; follow-ups are platform-scoped, not connection-scoped. This is exactly the side-effect detail an agent needs for a destructive toggle.

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 purpose, then dense but purposeful paragraphs on each switch's behavior and the failure modes. Every sentence carries information, though the error-code parentheticals and platform note make it long for a four-parameter toggle.

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

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

With no output schema and only partial schema coverage, the description carries most of the burden and does so well: failure codes, side effects, and recovery caveats are all present. Minor omissions remain (e.g., whether omitted switches are left untouched, and what a successful response contains).

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 50%: both UUIDs are documented in the schema, but respond_to_comments and respond_to_messages have no schema descriptions. The description compensates by explaining what each switch governs and its downstream effects, though it never names the parameters directly, leaving the mapping to inference.

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 ('Switch the AI on or off for a connection') and enumerates the two axes affected (messages, comments). It implicitly scopes to a connection, which distinguishes it from the conversation-level sibling resume_conversation_ai, but it never names that alternative explicitly.

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

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

Gives concrete operational conditions: at least one setting must be sent or 422 no_settings; a disconnected connection cannot be changed (409 connection_inactive); reconnecting resets both switches so they must be set again. It offers no explicit when-to-use guidance against sibling tools like resume_conversation_ai or update_follow_up_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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, so safety is partly covered. The description adds genuinely new behavioral context: it discloses partial-merge semantics ('Changes the fields you send') and that email/platform ids are read-only identity fields. It does not, however, explain the destructiveHint=true implication (what gets overwritten or lost).

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

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

Two short sentences, front-loaded with the purpose before the constraint. 'Changes the fields you send' is slightly informal but every sentence earns its place with no 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 mutation tool with no output schema and nested custom_fields, the description covers the key gotcha (partial update, read-only identity). It leaves the destructiveHint=true and idempotent behavior unexplained, so an agent cannot fully predict the consequences of the call.

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

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

At 67% schema coverage the schema carries most weight, fully documenting mobile, agent_id, contact_id and custom_fields, while name and status remain bare. The description adds partial-update semantics and the read-only identity-field note (email, which is not even a parameter), so it contributes some meaning but does not fully compensate for the undocumented fields.

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 clear verb+resource ('Update a contact') and adds scope via 'Changes the fields you send', making the partial-update nature explicit. It does not, however, name any sibling (e.g. update_lead, get_contact) to differentiate itself in a crowded set of update_* tools.

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/when-not guidance and no mention of alternatives among the many update_* siblings. The reader must infer from 'Changes the fields you send' that this is the correct tool for editing an existing contact, but nothing tells them when to reach for update_lead or get_contact instead.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description goes beyond them by disclosing the authorization model (author-only edits) and two specific failure modes with error codes, which is exactly the kind of auth/constraint context the 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?

The critical operation ('Rewrites the note's text') is front-loaded, followed by the permission constraints. The only waste is the first line repeating the title 'Edit a note', a minor redundancy in an otherwise tight description.

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

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

For a destructive mutation tool, the description covers the key behavioral concerns: authorization rules and immutable-note errors. With 100% schema coverage and safety annotations present, it is nearly complete; it only omits any note about the return/confirmation behavior, though no output schema exists to carry that.

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

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

Schema description coverage is 100%, so all four parameters (agent_id, contact_id, note_id, text) are already documented in the schema, including the text length bounds and error codes. The description adds no parameter-level syntax or format meaning beyond that, 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?

The description states a specific verb+resource: 'Rewrites the note's text'. This makes it immediately distinguishable from create_contact_note (which authors a new note) and list_contact_notes (which reads them). An agent can identify the operation without ambiguity.

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

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

It clearly articulates the when-not conditions: only the note's author may edit ('403 not_note_author' otherwise) and system notes cannot be edited ('403 system_note_read_only'). It does not explicitly name a sibling alternative, but the preconditions are strong enough to route an agent correctly.

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 (idempotentHint, destructiveHint): it explains that urgent true/false map to dashboard actions, both clear needs_attention, resolving resets an unhappy sentiment to neutral, the AI re-reads urgent/needs_attention on each reply so marks expire, is_read never sends a read receipt, and a no-change write is a no-op. This is rich, non-obvious behavioral disclosure consistent with the annotations.

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

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

Front-loaded with the one-line purpose followed by dense but each-sentence-earns-its-place detail. It is on the longer side but the length is justified by the interaction complexity between urgent, needs_attention, sentiment, and ai_enabled.

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

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

For a 6-parameter mutation tool with no output schema, the description covers the write semantics, side effects, and the sibling alternative thoroughly. The only gap is that it does not describe the response shape, though annotations and schema carry most of the remaining load.

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 high (83%), so the baseline is 3, but the description adds meaning beyond the schema by tying urgent/sentiment/needs_attention interactions together and clarifying AI-read timing for ai_enabled. The status enum meaning is left to the schema, which is fine at this coverage level.

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 (change) and resource (a conversation's state) and enumerates exactly which fields are affected: status, read for the team, urgent, and the AI switch. It even names the sibling resumeConversationAi as the alternative for one case, so an agent can distinguish it from related tools 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?

Gives a clear routing rule: a pause started by a teammate's reply is ended with resumeConversationAi instead of ai_enabled:false. That is explicit context for choosing between alternatives, but there is no general statement of when to reach for this tool versus, say, assign_conversation or update_contact.

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

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

Annotations already declare this a destructive (but idempotent) mutation, so the safety profile is covered. The description adds real behavioral context beyond that: steps and platforms exhibit replace-not-merge semantics, the server reorders steps by delay, and all validation happens before any change (atomicity). It stops short of stating reversibility 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 core action leads, followed by tightly packed constraints in three short sentences with no filler. Density is high but each clause (partial-update requirement, replace semantics, validation ordering) 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 4-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the key gaps: partial-update rule, replace semantics, ordering, and atomic validation. Only the boolean enabled parameter and post-update result behavior are left unexplained.

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% and the schema already documents delay_minutes limits and the 404/403 agent_id errors. The description adds the crucial semantics the schema omits: sending steps or platforms replaces the whole existing set, and the server sorts steps by delay. The enabled flag still has neither a schema nor description explanation.

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

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

States a specific verb and resource: updating an agent's follow-up settings. This cleanly distinguishes it from the read counterpart get_follow_up_settings listed among siblings, though the description itself never names that sibling to reinforce the split. It is clear but relies on the tool name for 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?

Implicitly signals a partial-update tool by requiring at least one field ('Changes the parts you send'), and names the 422 no_settings failure when none are sent. However, there is no explicit when-to-use guidance versus alternatives like update_agent, or any prerequisite note about needing a prior get_follow_up_settings read.

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

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

Adds substantial behavior beyond the annotations: invalid status transitions return 422 invalid_request, status changes are written to the contact timeline, API edits skip the dashboard's auto-assignment behavior, and re-sending the current pinned state is a no-op. These are exactly the failure modes and side effects an agent needs before calling.

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 verb+resource, then layered constraints in descending importance. The pinned explanation is repeated verbatim in the schema and the opening line duplicates the title, so there is minor redundancy but no wasted bulk.

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

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

For an 8-parameter tool with a nested custom_fields object and no output schema, the description covers the risky semantics (status moves, assignment, pinning). It leaves custom_fields key/merge behavior to the schema, which documents it thoroughly, so the agent has enough to call 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 75% and the schema itself documents phone, pinned, status and the custom_fields merge semantics in detail. The description's notes on status values and pinned idempotency largely restate the schema rather than adding format or edge-case detail beyond it, 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?

States a specific verb and resource (update a lead) and immediately scopes what changes: only the fields you send. It explicitly separates itself from the sibling assign_lead by noting that API edits never assign an unassigned lead, which assignLead does.

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

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

Gives a clear conditional route to the alternative tool for assignment and explains status-move limits, so an agent knows the boundary. It does not name a read tool (e.g. get_lead) or state when not to use update_lead, so it stops short of explicit 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 destructiveHint=true and idempotentHint=true, so 'Replaces the prompt' and 'sending the prompt the agent already has changes nothing' largely restate structured data. The description does add genuinely new behavior: propagation timing (usually within a minute), the off-state caveat that no leads are saved until re-enabled in the dashboard, and the 404 lead_capture_not_found 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?

Front-loaded and information-dense, with every clause carrying weight. The opening line duplicates the name and title verbatim, which is a minor but real 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 tool with no output schema and full annotation coverage, the description supplies everything an agent needs: scope limits, effect timing, off-state behavior, and the key error. Nothing material is 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%, so the baseline is 3; both parameters are fully documented in the schema including trimming rules and error codes. The description adds scope meaning beyond the schema by clarifying that lead capture has other settings which cannot be sent and that extra fields are ignored.

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 ('Update the lead capture prompt') and immediately narrows scope with 'Replaces the prompt' and 'Only prompt is taken'. This cleanly separates it from the read-only sibling get_lead_capture and from update_agent, which handles the tool's other settings.

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 operational context: changes take effect on next replies, re-sending the current prompt is a no-op, and the prompt can be edited while the tool is off. It stops short of explicitly routing the agent (e.g. 'call get_lead_capture first to read the current prompt'), so there is no named alternative.

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