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 already declare destructiveHint=true and idempotentHint=true, so safety is covered; the description adds real value by stating the effect ("the invitation link stops working at once") and its immediacy. It stops short of noting whether the action is reversible or what permissions are required.

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

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

Two short sentences, action first and consequence second, with no filler. Every word 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 single-parameter destructive tool whose annotations carry the safety profile and which has no output schema, the description covers the essential effect. Minor gaps remain around reversibility and auth prerequisites.

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 only one parameter and schema coverage is 100%; the schema already documents invitation_id with its source (listInvitations) and the 404 behavior for another company's invitation. The description adds nothing beyond that, 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 ("Cancel an invitation") that is unambiguous and clearly distinct from the nearest siblings (resend_invitation, list_invitations, invite_member). It does not explicitly name or contrast with those siblings, 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 no when-to-use, when-not-to-use, or alternative guidance. It never mentions resend_invitation or list_invitations, which an agent would need to route correctly between canceling, resending, or listing invitations.

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 annotations, it discloses the initial inactive/no-media state, immutability of type once media is stored, and the runtime effect of name, when_to_send, and description on every AI reply. It also explains response message_weight and notice handling, and does not contradict the non-destructive/non-idempotent annotations.

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

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

The text is front-loaded and mostly dense with lifecycle and response details. It repeats the title in the opening line and could be structured more sharply, but no sentence is clearly disposable.

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 six-parameter creation tool with no output schema, it covers the full create-to-media-to-activate lifecycle, active-state effects, and relevant response fields. The only notable omission is priority semantics, while authorization details are already in the schema.

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

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

Schema coverage is 33%, and the description compensates for key parameters by explaining type's media role and immutability, plus how name, when_to_send, and description affect active AI behavior. It leaves priority undocumented in both schema and description, so compensation is useful but incomplete.

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

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

The description states a specific verb and resource ('Add an AI attachment') and immediately scopes it as a new, switched-off attachment without media. It names the follow-up media and activation tools, so an agent can distinguish this from import_attachment_media and update_attachment.

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

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

It gives an explicit lifecycle sequence: create, attach media via uploadAttachmentMedia/importAttachmentMedia, then activate with updateAttachment and active:true. It also explains when media is sent and what fields affect replies, so when to use this versus alternatives is clear, with only a minor naming mismatch against the snake_case sibling list.

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?

With annotations already declaring the mutation and destructive profile, the description adds valuable context beyond them: the agent's AI context is rebuilt in the background 'usually within a minute,' and the response's `message_weight` and optional `notice` are explained. It does not cover permission errors, though the agent_id schema does.

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

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

The description is front-loaded with the purpose and avoids filler. The sentence about `message_weight` is slightly dense but earns its place by explaining the response without an output schema.

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 create tool with no output schema, the description usefully explains the background rebuild and response fields. However, it leaves the required `name` parameter and `tags` array undocumented anywhere, which is a notable gap for an agent trying to invoke this 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 only 50%, and the description adds no meaning for the undocumented required `name` parameter or the `tags` array. The content and agent_id parameters are already well-documented in the schema, so the description does not 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?

The description states a specific verb and resource: 'Add knowledge to an agent' and 'Text knowledge, linked to the agent.' An agent can tell this creates a text knowledge entry for an agent, but it does not differentiate from siblings like replace_knowledge_base or create_attachment.

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

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

The phrase 'Text knowledge, linked to the agent' implies this is the tool for adding new text knowledge, but there is no explicit when-to-use guidance and no mention of when to prefer replace_knowledge_base or other alternatives.

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

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

Annotations already 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 readOnly=false, destructive=false, and idempotent=false, so the safety profile is covered. The description adds genuinely new behavioral context: that the field is inserted before built-in fields, that AI lead capture begins within roughly a minute, and that 50 custom fields triggers 422 lead_field_limit_reached. Some error content duplicates the `key` schema description, which caps this below 5.

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

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

Purpose and ordering are front-loaded, and each sentence carries information. There is mild redundancy where the reserved-key and 409 error codes are restated already present in the `key` parameter description, 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 create tool with no output schema and fully covered input schema, the description covers placement, background collection, and failure modes. The main omission is what the call returns, though with no output schema this is 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 description coverage is 100%, so the baseline is 3. The description restates semantics for `label` and `required` (what tells the AI to ask, treating the field as needed) but adds little that the schema does not already 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?

The description states a specific verb+resource ('Adds a custom field to the agent's lead form') and specifies where the field lands relative to existing fields. It is clearly distinguishable from create_lead, update_lead_field, and delete_lead_field 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?

Usage is implied by the ordering and side-effect explanation, but the description never names alternatives or states when to use this versus update_lead_field or list_lead_fields. No explicit when/when-not guidance is given.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds a real behavioral fact beyond them – the creation is text-only and media arrives in a separate follow-up call. It says nothing about failure modes (duplicate shortcut rejection), permissions, or what the response contains.

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

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

Three short sentences, the creation-then-media dependency front-loaded ahead of the constraint. The opening line restates 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?

No output schema exists, yet the description never says what the call returns – notably whether the new reply's id comes back, which is required to chain into importSavedReplyMedia. For a create tool whose documented follow-up depends on a returned identifier, this leaves a meaningful hole.

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 parameters are already well documented (content/media interaction, agent_id error codes, shortcut uniqueness all live in the schema). The description reinforces shortcut uniqueness but adds no new parameter meaning, which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Create a saved reply') and names the key artifact ('a new saved reply with text'), which is clear enough to distinguish from replace_saved_reply or list_saved_replies. It does not explicitly contrast itself with replace_saved_reply or any sibling, 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?

Provides one genuinely useful workflow pointer: add media afterwards via importSavedReplyMedia, and that shortcut must be unique in the agent. However, there is no guidance on when to use this versus replace_saved_reply, nor any prerequisite or exclusion statements, so usage is largely 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?

Beyond the annotations, it discloses the 24-hour staging lifetime, pending vs ready states, 15-minute upload URL validity, 20-second download window, redirect limits, accepted formats and 20 MB cap, type detection from bytes, per-feature scope checks, and a 10 requests/minute budget per key. This is rich operational context that annotations alone do not 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 long but well-structured, front-loading the two usage modes with bullets and a concrete curl example. Most details earn their place for a nested, non-idempotent creation tool, though it could be trimmed slightly without losing meaning.

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

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

For a complex tool with a nested file object, no output schema, and open-world network behavior, the description covers the missing pieces: return states, upload credentials, lifecycle, size/type limits, and authentication and rate-limit context. An agent has enough information to call it correctly and interpret the result.

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 real meaning: file_name and size_bytes must match the exact byte length sent to putUploadContent, file is a temporary https link shape with download constraints, and mime_type is explicitly not trusted. This goes beyond the schema's own field descriptions.

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

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

The description states a specific verb and resource: it creates an upload that stages a file for 24 hours for use as a media link. It clearly explains both creation modes, though it does not explicitly differentiate this tool from nearby siblings such as create_attachment.

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 exactly when to use each mode: send bytes directly with file_name and size_bytes, or hand over a file link via the file object. It also gives lifecycle and scope guidance, but does not name alternatives or exclusions such as when to use create_attachment 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?

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false): it discloses the 201 response with a usually-pending template, that only approved templates can be sent, the review lifecycle, the 422/409 error taxonomy with error codes, the specific trap that a retried create after a lost response meets 409 template_name_taken, and the 10 requests/minute per-key budget. The media_url fetch contract (no redirects, must answer 200 with Content-Type, public address, 16 MB cap, downloaded once) is behavioral detail an agent could not infer.

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 purpose and outcome, then organized by category/body, media, and error/rate-limit concerns — a sensible order for a 12-parameter nested tool. It is long, and the media_url rules restate almost exactly what the schema description already says, which is the main waste.

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

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

No output schema exists, so the description must carry return-value semantics, and it does: the 201 shape, the pending/approved/rejected states, rejected_reason, and field-level 422 vs. template_rejected 422 vs. 409 name collision. Combined with the variable, media and rate-limit rules, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 83%, so the schema carries most parameter documentation; the description still adds meaning the schema does not, notably that Meta may re-file a category and the response shows where it went, the one-variable-style-for-the-whole-template rule, and the authentication-template shape (only `otp`, Meta writes the text). Much of the media_url explanation duplicates the schema verbatim, limiting it to a 4.

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 immediately scopes it: 'submits a new template on one of the agent's WhatsApp numbers for Meta's review,' with the explicit analogy to the dashboard. It routes the reader to the correct siblings by name (getWhatsAppTemplate for review status, sendWhatsAppTemplate for sending), so it is clearly distinguishable from list/get/update/send template 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?

Gives concrete when-to-use context (creating in the dashboard vs. here) and explicit when-not guidance: location headers, carousels, limited-time offers, catalog and Flow buttons must be made in WhatsApp Manager because this endpoint cannot create them. It also tells the agent how to handle a retried create (read the list and carry on). It does not explicitly contrast against update_whatsapp_template, but the create-vs-edit boundary is implied by the media_url 'on an edit' note.

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

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

Beyond the annotations, the description discloses important consequences: the deletion is permanent, stored files are removed, the AI stops offering the attachment on its next reply, and previously sent messages keep the attachment but its media no longer opens. That is specific, useful side-effect information for a destructive operation.

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

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

The description is front-loaded and efficient, with the permanence and downstream effects stated immediately. The first line repeats the title verbatim, which is a minor redundancy, but the remaining sentences each add useful 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 two-parameter destructive tool, the annotations already declare destructive and idempotent behavior, and the schema fully documents parameters and error cases. The description completes the picture by explaining what is destroyed and what happens to existing messages and media, leaving no significant ambiguity for correct invocation.

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

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

Schema description coverage is 100%, and both required parameters already have detailed error semantics in the schema. The description does not add any new parameter-level meaning, so it meets the baseline for a fully documented schema without exceeding it.

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

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

The description names a specific verb and resource: delete an AI attachment. It also states the scope clearly by noting that the attachment and its stored files are deleted, distinguishing it from siblings such as update_attachment, get_attachment, and create_attachment.

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

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

The description makes the use case clear: permanently remove an attachment so the AI stops offering it. However, it does not explicitly route the agent away from alternatives such as update_attachment or explain when deletion should be avoided, 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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them: the 403 not_note_author and 403 system_note_read_only conditions tell the agent that only authored notes can be deleted and system notes are protected.

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 lines with no wasted words; the core action is front-loaded. The 'Same rules as editing' clause is terse and slightly cryptic, requiring knowledge of the update tool's docs, but it is not 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?

Adequate for a three-required-param delete with full annotations and full schema coverage, and it does disclose the key authorization failure modes. It stops short of confirming whether the deletion is permanent/hard vs soft or 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 description coverage is 100%, so all three UUID parameters and their error semantics (404 agent_not_found, 403 agent_not_authorized, 404 not_found) are already documented in the schema. The description adds no parameter-level 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 (delete) and resource (note). The name delete_contact_note and the sibling set (create_contact_note, update_contact_note, list_contact_notes) make the target unambiguous. It does not, however, explicitly distinguish itself from those siblings in prose.

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

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

There is no when-to-use vs alternative guidance and no prerequisites stated. The 'Same rules as editing' cross-reference is about error behavior, not about when to pick this tool over update_contact_note or the other delete_* siblings.

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

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

Annotations already supply destructiveHint, idempotentHint and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely non-obvious context beyond that: the effect is deferred ('stops using it on its next replies') and the site's login credential survives deletion for the site's other and future tools. It does not cover auth/permission requirements, but the added semantics are substantive.

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?

Compact and front-loaded, with the destructive effect and the credential-retention caveat stated up front. It loses a point because the opening line merely restates the title before the actual content, and the final sentence's phrasing ('for the site's other tools and the next one') is slightly compressed.

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 destructive tool with full annotation coverage and complete schema parameter documentation, the description covers what an agent needs: what is destroyed and what is preserved. It lacks any note on whether deletion is reversible or requires elevated permissions, which is the main remaining gap.

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

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

Schema description coverage is 100%, and both parameters carry rich descriptions including the exact error semantics (404 not_found, 404 agent_not_found, 403 agent_not_authorized). The description adds nothing further about tool_id or agent_id, so the baseline 3 applies.

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

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

The description pairs a specific verb ('Delete') with a specific resource ('custom API tool'), and the title/name match reinforces it. Among the many delete_* siblings, the resource noun alone makes it unambiguous which entity is destroyed.

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 statement of when to delete versus when to use an alternative such as update_custom_api_tool to disable the tool, nor any prerequisite/permission guidance. The closest thing is a consequence statement ('the AI stops using it on its next replies'), which describes an effect rather than a selection criterion.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses cascade behavior ('deletes it everywhere it is linked') and the shared-knowledge authorization constraint that yields 403 shared_with_other_agents — both materially affect invocation risk.

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 front-loaded, with the cascade scope stated before the error rule. The leading line restates the title, a minor redundancy, but nothing else 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?

For a destructive 2-param tool with full schema coverage and no output schema, the description covers the key gaps an agent needs: cascade scope and the authorization condition. It is largely complete, missing only explicit sibling routing.

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%; both agent_id and knowledge_base_id are documented in-schema with their 404/403 error semantics. The description adds no parameter-level detail, so the baseline 3 applies — the schema does all the work.

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

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

States a specific verb (delete) and resource (knowledge base), and the second sentence clarifies scope: it deletes the KB 'everywhere it is linked', which is more than the title conveys. It does not explicitly contrast itself with replace_knowledge_base or the other delete_* siblings, so differentiation relies on the reader inferring from the reference to the shared-knowledge rule.

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 alludes to an alternative operation ('the same shared-knowledge rule as replacing') and surfaces a failure condition (403 shared_with_other_agents), which implies when the delete will be refused. However, it never says when to choose delete vs replace, and gives no explicit when-not guidance, so routing 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?

Although annotations already declare destructiveHint=true and idempotentHint=true, the description adds substantial context they cannot convey: there is no undo, related entities survive, a repeat delete yields `404 not_found`, and re-saving from the same conversation creates a new lead. This is exactly the kind of behavioral detail that goes beyond 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?

Sentences are dense and each carries information, with the permanence warning front-loaded. The opening line merely restates the title, a minor redundancy, but the rest is efficient 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?

For a destructive two-parameter delete with no output schema, the description covers what is destroyed, what is preserved, repeat-call behavior, and the post-delete lifecycle. Nothing an agent needs to invoke it safely 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%, and the parameter descriptions already document the `404 not_found` / `403 agent_not_authorized` behavior for agent_id and lead_id. The description adds no syntax, format, or meaning beyond the schema, 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?

The description states a specific verb and resource — 'Deletes the lead permanently: there is no undo' — and immediately scopes it against lookalike siblings like delete_lead_field by clarifying that contacts, notes, and the conversation are untouched. An agent can distinguish this from the other delete_* tools without opening a schema.

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

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

Usage is implied by the destructive framing, and the note 'Contacts can't be deleted through the API' draws a boundary. However, there is no explicit when-to-use guidance or named alternative (e.g. update_lead, delete_lead_field), so the agent must infer selection from the resource 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 flag destructiveHint and idempotentHint, but the description goes well beyond them: it explains that values are retained under the key, that the dashboard hides them, that the AI stops collecting within a minute, and that built-in fields return 422. This is exactly the kind of ordering/side-effect context an agent cannot infer from annotations.

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

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

Front-loaded with the action verb, then layered with consequences and failure mode in tight sentences. The repeated title line is the only redundancy and is negligible.

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 fully covers the mutation's effects, timing, reversibility, and error behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with both agent_id and field_key fully documented including their error codes. The description adds behavioral context (custom_fields, key persistence) but no new parameter semantics, so the baseline 3 applies.

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

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

States a specific verb+resource (delete a lead field) and adds scope detail about what is removed. It is clearly distinguishable from create_lead_field, update_lead_field, and delete_lead among siblings.

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

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

The description makes the deletion context clear and implicitly excludes built-in fields via the 422 system_field rule, telling the agent when the call will fail. It does not explicitly route to alternatives like update_lead_field for non-destructive changes, so no full when-to-use-this-vs-that 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, but the description adds substantial unannotated behavior: irreversibility ('It can't be undone'), a 30-day Meta name lock, the specific 409 error codes and their triggers, and the fact the lookup only scans the first 100 templates. This goes well beyond what the structured fields convey.

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

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

Front-loaded with the action and its scope, then layers failure modes efficiently in a few dense sentences. Slightly heavy on stacked conditionals and the leading line repeats the title, which is minor waste.

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

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

No output schema exists, and for a destructive operation the description supplies the safety-critical context an agent needs: irreversibility, the name-lock acknowledgement requirement, and refusal conditions. It does not discuss return payload shape or pagination of the underlying template list, but little else 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 agent_id, template_id, connection_id and acknowledge_name_lock are already documented in the schema, including their 404/403 error mappings. The description reinforces acknowledge_name_lock's consequence but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Delete a WhatsApp template') and immediately narrows scope: it deletes only one language version while the template's other languages remain. This distinguishes it cleanly from get_whatsapp_template, update_whatsapp_template and list_whatsapp_templates without needing their schemas.

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

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

Gives strong operational conditions: approved/paused templates require acknowledge_name_lock=true, disabled templates cannot be deleted, and templates in active broadcast or used by notifications are refused with 409. It does not explicitly route the agent to an alternative (e.g. update_whatsapp_template to disable first), so it stops short of a 5.

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

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

The annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world) and the schema documents the 404/403 failure modes, so the description is not obligated to restate them. What it adds is return-content context (the ad's metrics and provenance), which is useful but is output description rather than operational behavior such as auth, rate limits, or side effects.

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

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

Two sentences, front-loaded with the resource and its contents, then the id provenance. Every clause carries content, though the dense parenthetical lists make it slightly heavy to parse.

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 two fully-covered parameters, the description is the sole source of return-value information and it delivers: it names the entity, its fields, and the attribution data returned. Combined with the id-provenance guidance and the sibling route, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining how to obtain ad_id (latest_ad_id, attribution touch, list_ads item), which the schema's terse 'One of the agent's ads' does not convey. agent_id semantics (authorization scoping) are left to the schema, so it is not a full 5.

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

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

Names a specific verb (get) and resource (one Meta ad) and enumerates the concrete fields returned: title, media, catalog product, and attribution rollups (taps by channel, private replies, conversations/contacts/leads). It also situates the tool against the sibling list_ads by naming it as a source of ids, so an agent can tell get from list without opening schemas.

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

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

Explicitly tells the agent where a valid ad_id comes from — a conversation's latest_ad_id, the ad.id of an attribution touch, or an item of list_ads — which is exactly the context needed to invoke it. It stops short of an explicit when-not-to-use statement or a direct contrast with list_ads for enumeration, so it is strong but not complete.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description's added value is the error taxonomy and the return content detail (which settings are included beyond list-level basics). That is useful behavioral context beyond the annotations, though it stops short of describing response shape or any rate/permission nuances.

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?

Content is front-loaded: the returned-field inventory comes first, error conditions last. The opening line 'Get an agent' merely restates the title, and the error-code sentence duplicates the input schema, so a small amount of the text does not earn 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 carries the return-value burden and does so by naming the notable settings returned, plus the two failure modes. It is nearly complete for a simple single-resource read; only the overall response envelope/format is unspecified.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents agent_id and its error semantics. The description's 403/404 mapping largely repeats the schema text rather than adding new 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?

The description states a specific verb+resource (retrieve one agent with its settings) and enumerates the distinguishing fields: Main Instructions, AI handoff, comment auto-hide, ai_stop_enabled/ai_stop_when. It explicitly contrasts with the list tool ('besides the basic details the list returns'), so an agent can distinguish it from list_agents without reading schemas.

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

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

It clarifies the selection context by contrasting single-agent retrieval against the list, and gives concrete outcome conditions (404 for unknown/deleted/other-company agents, 403 for agents off the key's list). It does not explicitly address when to prefer get_agent_setup or get_agent_analytics, so the sibling exclusions are implicit rather than stated.

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

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

Annotations already establish 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description goes further by disclosing the return shape and thresholds like a knowledge base over 60,000 characters flagged in `attention`. It does not discuss authorization or failure behavior, though the schema's agent_id description already documents the 404/403 cases.

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

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

The purpose is front-loaded, which is good, but the body is a long comma-chained list of return fields packed into essentially one sentence. Given there is no output schema the enumeration earns its place, but it could be restructured for scanability.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly: enumerated stages, the five ordered steps, next.say, optional parts, attention items, live facts, and house rules. An agent knows what it will get back and how to act on it.

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

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

There is exactly one parameter and schema coverage is 100%, with the schema itself spelling out the 404 agent_not_found and 403 agent_not_authorized conditions. The description adds nothing about agent_id, so the baseline 3 applies.

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

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

The description concretely defines the resource — a setup-progress report for one agent — and enumerates its payload (stage, five steps, next.say, attention, house rules), which clearly separates it from get_agent (raw config) or get_agent_analytics. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

"Call it first when helping someone set up or improve an agent, and again after each change" gives a clear trigger and a re-invocation cadence. It stops short of naming alternatives or saying when NOT to use it (e.g., for reading raw agent settings use get_agent).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on what the returned attachment contains, no auth caveats beyond what the schema already states.

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

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

It is short, but the brevity is under-specification rather than conciseness — a four-word phrase that duplicates the title and conveys no information the caller did not already have.

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?

Structurally the tool is well-covered (annotations plus a fully documented schema, no output schema), but the description leaves the agent unable to differentiate this from get_attachment_media and list_attachments, which is the one gap the description was needed to fill.

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

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

Schema description coverage is 100% and both parameters carry detailed error semantics (404 agent_not_found, 403 agent_not_authorized, 404 not_found). With the schema doing full work on a 2-parameter tool, the baseline of 3 applies; the description contributes no additional parameter meaning.

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

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

Tautological: description restates name/title.

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

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

There is no when-to-use or when-not-to-use guidance. Critically, the sibling get_attachment_media exists and the description gives no signal about which one to pick when an attachment has media.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real value: a 15-minute link lifetime surfaced via `expires_at` and an explicit do-not-persist instruction. It omits that this is an authenticated call with per-key agent scoping, but the schema covers those error cases.

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

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

Three short sentences, front-loaded with the action and then the crucial expiry constraint; nothing is buried. The opening line largely restates the title, which is the only wasted token.

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

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

With no output schema, the description steps in to characterize the return value (ordered links plus `expires_at`), the volatility of those links, and the no-media edge case. That covers everything an agent needs to call this correctly and act on the result.

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

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

Schema coverage is 100% and both required UUID parameters are documented in the schema with their 404/403 outcomes, so the description is not obliged to compensate. It adds no extra meaning about agent_id or attachment_id beyond what the schema already states, which is the baseline-3 case.

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 links to an AI attachment's files') and clarifies that the result is one read-only link per stored file, in order. It never distinguishes itself from the nearby get_attachment / list_attachments / import_attachment_media siblings, so an agent still has to guess which of those to pick.

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

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

Offers genuine operational guidance for the result ('download the files within that time, or ask again; don't store the links') and covers the empty case. But it gives no condition for choosing this tool over get_attachment or list_attachments, so selection guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the description is not burdened with safety disclosure. It adds real value by explaining what the response contains (status and counts) and that counts track messages 'as WhatsApp reports it', implying they update over repeated reads.

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, front-loaded with the resource and payload, then the usage/routing hint. The only minor waste is echoing the title ('Get a broadcast') as the first line, which duplicates structured data.

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 reasonably carries the return-value burden by naming status and counts. Safety is covered by annotations and both parameters by the schema, leaving little an agent needs that is missing, though the exact shape of the counts is not elaborated.

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

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

Schema coverage is 100% and both parameters (agent_id, broadcast_id) are fully documented with error codes in the schema itself. The description adds no syntax, format, or meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and singular resource ('Get a broadcast', 'One broadcast') and immediately scopes the payload to its status and counts. It also names the sibling listBroadcastRecipients, so an agent can distinguish it from list_broadcasts (plural) and list_broadcast_recipients 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 routing to an alternative: use listBroadcastRecipients when per-recipient detail is needed, and this tool for overall status/counts. It also implies the polling pattern ('read it again to follow a broadcast'), but there are no explicit exclusions or prerequisites beyond that.

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

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

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 and destructiveHint=false, so safety is covered; the description adds value by detailing the return payload, including attribution semantics (latest touch, origin, ad title and Meta id). It does not discuss side effects or rate limits, but none are expected for a read tool.

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

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

Two sentences, front-loaded with the verb and resource, then the return contents, then the id-sourcing hint. Given there is no output schema, the field enumeration earns its space.

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?

Because no output schema exists, the description appropriately enumerates the returned fields and attribution structure, and the input schema carries error semantics. Only the structural shape of nested attribution objects is left slightly implicit.

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

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

With 100% schema coverage the baseline is 3, but the description adds provenance semantics for contact_id that the schema does not provide. agent_id semantics are left entirely to the schema, which is acceptable.

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 exact fields returned, which distinguishes it clearly from list_contacts and from get_lead. An agent can tell precisely what it gets back without opening a schema.

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

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

Explicitly tells the agent where to obtain the required contact_id ('from list_contacts or from a lead's contact_id'), which is real routing guidance. It lacks an explicit when-not condition (e.g. use list_contacts for bulk retrieval), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description contributes behavior beyond that: it specifies the read is scoped to one agent's single conversation and, with no output schema, enumerates what the response actually contains — the key thing an agent cannot infer elsewhere.

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 and resource, with the id-provenance instruction placed last where it belongs. It is a single dense run-on sentence with deep parentheticals, but every clause names an actual returned field or a routing alternative, so little 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?

With no output schema, the description carries the return-value burden and does so broadly — covering contact, channel, status, last message, read state, flags, AI state, assignee, and attribution provenance. Coverage of the response is solid; only minor gaps (identifiers/timestamps, message-history pointer) remain.

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

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

Schema description coverage is 100% and both parameters already document their 404/403 failure modes. The description adds only one semantic hint — that conversation_id comes from list_conversations — which is marginal over the schema, 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 ('Get one conversation of an agent') and then enumerates the exact payload: contact/channel, status, last message, read state, urgent/needs-attention flags, AI state, assignment, and attribution. It also names the sibling that supplies the id (list_conversations), so an agent can distinguish it from list_conversations and list_conversation_messages without opening schemas.

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

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

Gives clear entry conditions and routes to alternatives: 'Get its id from list_conversations' and points at list_conversation_ai_switches for who switched the AI and why. It stops short of explicit exclusions (e.g., use list_conversation_messages for the message history), so it is strong context rather than a complete when/when-not rule set.

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 cover readOnly, idempotent and non-destructive semantics, so the description need not restate safety. It adds genuine value beyond the structured data by disclosing what is returned (name, when-to-use text, method, URL, headers, body template, inputs, active flag, last test, site login) and a security-relevant constraint: secrets are never returned, only whether one is stored.

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 verb and resource, and every clause earns its place either by enumerating return payload or by pointing at the id source. The long field list is compressed into a single sentence rather than padded prose.

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 return-value inventory an agent needs, while error semantics live in the input schema and the safety profile in the annotations. Nothing required to call a 2-parameter, read-only getter 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%, including error semantics for both uuid parameters (404 not_found, 404 agent_not_found, 403 agent_not_authorized), so the schema does the heavy lifting and the baseline is 3. The description contributes only the origin of tool_id via list_custom_api_tools, a small addition over 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 with scope ('Get one custom API tool of an agent') and enumerates exactly which fields are returned, so the agent knows what the call yields. It also routes the agent away from guessing the id by pointing at the sibling list_custom_api_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?

Provides a clear prerequisite and routing hint ('Get its id from list_custom_api_tools'), which effectively tells the agent when this tool applies versus the listing sibling. It stops short of explicitly stating when not to use it (e.g., vs. list_custom_api_tool_runs or update_custom_api_tool), so it is not a full when/when-not treatment.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuine behavioral context beyond that by spelling out what fields come back, including attribution details (origin touch, ad title, Meta id) that annotations cannot convey.

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

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

Front-loaded with the verb and the single-object scope, followed by a compact returned-field inventory and a short id-sourcing pointer. The field list is long but every item is meaningful payload information, with no filler 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?

With no output schema, the description takes on the return-value burden and does so thoroughly, enumerating fields and nested attribution. Required params, error codes, and id provenance are covered between the description and the schema, leaving nothing an agent 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% and both parameters carry their own 404/403 semantics in the schema, so the description need not document them. It contributes only the indirect hint that lead_id comes from list_leads, which is the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get one lead of an agent') and enumerates the payload it returns (name, phone, status, AI summary, custom fields, assignment, pin state, ids, attribution origin). It also distinguishes itself from list_leads, so an agent can separate the single-lead fetch from the bulk listing.

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

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

The closing sentence 'Get the lead's id from list_leads' gives clear, actionable context for when and how to reach this tool, chaining it after the listing call. It offers no explicit when-not or exclusion cases, which keeps it short of a 5.

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

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

Annotations already declare 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?

Beyond the read-only/idempotent annotations, the description discloses important behavior: the raw key is never returned, `prefix` and `last_four` are shown instead, and when called with an AI assistant sign-in token the response carries a `grant` rather than a `key`. These are meaningful response-shape and access-model details 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?

The description is front-loaded with purpose and key usage guidance, and most sentences carry useful context. The opening line repeats the title, which is slightly redundant, 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?

With no output schema and no parameters, the description fully carries the burden of explaining the return shape: key metadata vs grant metadata, the masked key fragments, and the first-call use case. Nothing essential for invoking and interpreting the tool is missing.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool applies, and the description does not introduce confusion about inputs.

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

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

The description states a specific verb and resource: describe the calling key or connection. It distinguishes the two cases (API key vs AI assistant sign-in token) and explains exactly what identity/access information is returned, so an agent can distinguish it from sibling get_* 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?

It gives clear usage context: any valid key may call it, whatever its scopes, and it is the first call to make to check that a key works and see what it can reach. It does not explicitly name when not to use it or compare against a sibling, but the primary use case is unambiguous.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the description doesn't need to re-state safety. It adds genuinely non-obvious context: that the response includes the raw request/response payloads and the associated ad and conversation. Error semantics (404 not_found, 403) live in the schema rather than here, which is fine.

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 verb, zero filler. The field enumeration is dense but each item tells the agent something it would otherwise have to discover by calling the 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?

With no output schema, the description carries the burden of describing what comes back, and it does so by naming the major fields (tool identity, outcome, conversation, ad, request, response). Slightly more on the payload shape would make it fully self-sufficient.

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

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

Schema coverage is 100% and both parameters carry detailed descriptions including cross-agent and cross-company 404/403 behavior. The description only adds provenance for run_id ('Get its id from list_tool_runs'), which is a small but real addition over the schema's 'One of the agent's tool runs'.

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 tool run of an agent') and enumerates the payload it exposes: provider/operation, outcome, conversation, ad, request and response. That enumeration makes it immediately distinguishable from list_tool_runs and get_conversation.

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 list_tool_runs to obtain the run_id, which is the main prerequisite for calling this tool. It doesn't state any when-not condition, but a single-record fetch has few plausible alternatives.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description's real value is the added 404 semantics: bytes not yet sent, past the 24-hour window, or belonging to another agent. That is genuine behavioral context beyond the structured fields, though it doesn't discuss return shape beyond the field list or any rate/consistency behavior.

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

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

Two sentences, front-loaded with the operation and then the returned fields, with the error condition last. The opening 'Get an upload' largely restates the title, a minor redundancy, but nothing else 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?

With no output schema, the description carries the burden of describing returns and does so by naming the key fields (type, size, SHA-256, expiry). Combined with the 404 conditions and fully documented params, an agent has enough to call it correctly, though a fuller return description would be ideal.

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% — both agent_id and upload_id already document their UUID format and the exact 404/403 outcomes for foreign or missing resources. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get an upload') and immediately enumerates what the stored upload contains — bytes type, size, SHA-256, expiry — which distinguishes it from write siblings like create_upload. It stops short of naming a near-alternative such as get_attachment, so sibling differentiation is only implicit.

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

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

Usage is implied by the resource description rather than stated: the agent can infer it should call this to inspect a single known upload, but there is no explicit 'use this when… / use X instead' guidance against get_attachment or list_attachments. The 404 rules describe failure conditions, not when-to-use policy.

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, so the safety profile is covered; the description adds genuinely new behavior: visibility is scoped by which agents the key or assistant can reach, and out-of-scope ids return `404 message_not_found` indistinguishable from an unknown id. That 404-equivalence detail materially changes how an agent should interpret a failure. It does not describe latency or delivery-state progression, keeping it at 4.

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 sentence is front-loaded and the scoping caveat follows it, so the essential use case is read first. The second paragraph is dense but every clause (which sends, which key, the 404 rule) carries information; a small amount of repetition of the first line exists between title and body.

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 is the only place the return value could be explained — yet it never says what a status looks like (e.g. sent/delivered/read/failed) or whether it is polled over time. For a status-lookup tool with no output schema, that is a real gap, though the access-scoping and 404 semantics are well covered.

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

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

Schema coverage is 100% for the single parameter and the schema already says 'The `id` returned from a previous send'; the description's 'by the `id` the send returned' restates the same fact. Baseline 3 applies when the schema carries the parameter meaning.

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

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

Names a specific verb ('look up the status') and a specific resource ('a previously-sent message'), and ties it to the exact producer tools (`sendWhatsAppMessage` / `sendWhatsAppTemplate`) plus the `id` they return. An agent can distinguish this from `get_whatsapp_template`, `list_conversation_messages`, or `get_tool_run` 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?

States the precondition clearly: this is for messages already sent via the two send tools, and the input is the id the send returned. It does not explicitly exclude alternatives (e.g. `list_conversation_messages` for browsing a thread), so it stops short of full when/when-not guidance, but the usage context 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?

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses three concrete traits: data is read live from Meta, it is limited to templates among the 'first 100 the list reads,' and it shares a budget of 10 requests/minute per key. These constraints materially affect how an agent should call it.

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

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

Purpose and scope are front-loaded, and the sentences carry useful density without padding. Slightly information-dense in the second sentence, but nothing is wasted.

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

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

With annotations covering the safety profile, full schema coverage, and no output schema, the description supplies the remaining behavioral gaps (freshness, cap, rate limit). It is essentially complete for an agent to invoke 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 each parameter already documents its format and failure modes (404/403 errors). The description adds no parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (a WhatsApp template), and immediately scopes it as 'One language version of a template, as listWhatsAppTemplates shows it,' which distinguishes it from the list sibling without opening either schema.

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

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

Gives a clear use case ('how a new or edited template's review is followed') and references the list tool as the source of the ID, plus practical cadence advice ('check a review every few minutes, not every second'). It stops short of an explicit when-not-to-use statement but the context 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?

The annotations declare readOnlyHint=true, but the description discloses a write side effect: 'if the agent has none yet, this call sets it up with the defaults, switched on.' A get-or-create that registers and enables a widget modifies state, which directly contradicts the read-only annotation. An agent trusting the annotations alone would be surprised by the state change, so this is an Annotation Contradiction.

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

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

Front-loaded with the core purpose, then layered with genuinely useful detail (get-or-create behavior, the two embed variants, paste instructions, where changes live). It is on the longer side for a single-parameter tool, but every sentence earns its place 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?

With no output schema, the description carries the return-shape burden and does so adequately by explaining `embed_code.default` vs `embed_code.headless` and how each is consumed. It covers creation behavior, install semantics, and mutation redirection; only fine-grained error/return detail is left to elsewhere.

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

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

Schema description coverage is 100% — the single `agent_id` parameter already documents its format and the 404 `agent_not_found` / 403 `agent_not_authorized` failure modes. The description adds no parameter-level meaning of its own, 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 ('Get an agent's website widget and embed code') and goes further by naming the two returned variants (`embed_code.default`, `embed_code.headless`) and what each does. An agent can distinguish this from siblings like `get_agent` or `update_agent` 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 operating context: every agent has exactly one widget, the call is the same one the dashboard shows, and the embed snippets must be pasted once per page before the closing body tag. It also draws an exclusion line — 'Changing the widget stays in the dashboard' — so the agent knows not to attempt mutations here. It does not explicitly contrast against sibling read tools, so it falls short of a 5.

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

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

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 declare destructive/idempotent/openWorld, but the description goes well beyond them: atomic replacement semantics ("Nothing stored changes until every file passes"), fetch constraints (must return 200, 20s timeout, no redirects followed, non-public addresses refused), specific error codes (422 attachment_media_url_invalid, 422 invalid_media, 503 media_processing_busy), and a shared rate limit of 10 req/min per key with uploadAttachmentMedia.

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 purpose and the key constraint (replaces stored media) before error and rate-limit detail. The opening line duplicates the title and could be folded away, but the remaining sentences each add actionable information.

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

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

For a destructive, open-world, no-output-schema tool, the description covers failure modes, atomicity, encoding side effects and rate budget thoroughly. It does not describe what a successful response returns (e.g. the resulting media records), which is the only notable 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 `urls` schema description already contains the one-vs-ten album rule and the createUpload URL option, so the description largely restates it. Baseline 3 applies since the schema carries the parameter semantics.

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

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

States a specific verb and resource (put media on an AI attachment from links) and immediately distinguishes itself from `uploadAttachmentMedia` and from the `createUpload` URL variant. An agent can tell exactly what this does versus get_attachment_media and import_saved_reply_media.

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 selecting condition: "For a client that can't send files, such as an AI assistant," which contrasts with the direct-upload sibling. It also notes that a link may be a `createUpload` URL of this agent, linking it to that tool. It stops short of an explicit "use uploadAttachmentMedia instead when you have the bytes" instruction.

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 existing media is replaced, that all links are validated before any stored state changes (atomicity), per-type format/size ceilings, a 20-second fetch timeout, the specific failure code `422 media_url_invalid`, and a 10-request/minute per-key budget. These are exactly the risk factors an agent needs for a destructive, open-world write.

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: the first sentence states the action and the replacement semantics, then constraints follow in decreasing relevance (validation, formats, errors, rate limit). Dense but nearly every clause carries operational information; a small amount of overlap between the title line and the opening sentence.

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

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

For a destructive write with no output schema, it covers failure modes, atomicity, and rate limits well. The remaining gap is what the call returns on success (media objects? the updated saved reply?) and whether the replacement is reversible, neither of which is stated anywhere.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real meaning by tying cardinality to intent (one file vs. up to 10 ordered images for an album) and by attaching format and size limits to the link values. agent_id and saved_reply_id error semantics are 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 a specific verb and resource ('Put media on a saved reply'), plus the operative qualifier 'from links' and 'Replaces the saved reply's media', which makes the mutation semantics unambiguous. It does not name any sibling (e.g. import_attachment_media, replace_saved_reply, create_upload) to explicitly differentiate, which keeps it from a 5.

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

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

Gives concrete conditions for use: links must be https, public, no redirects, resolved within 20 seconds, or be the `url` of a Mojeeb upload of this agent — which effectively states the two valid input sources. It never says when to prefer another tool (e.g. direct upload) or when not to call it, so no explicit alternative routing.

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

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

Beyond the annotations (which declare destructive and non-idempotent), the description discloses the 7-day link validity, join-on-accept behavior, replacement of the prior open invitation, the 409 already_member outcome, and a concrete rate limit (10 req/min shared with WhatsApp template/broadcast endpoints). This is unusually rich behavioral context not derivable 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?

Front-loaded with the action, then the behavioral details, and the rate-limit note is legible. The leading line duplicates the title/verbatim action, a minor waste, but the rest 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, a description for a mutation tool should ideally say what the call returns (e.g. the created invitation), which is absent. Otherwise it is complete: role semantics, agent scoping, error cases, expiry, and rate limits are all covered.

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 property descriptions already explain role, email, agent_ids, and all_agents in detail. The description largely restates that (e.g. 'required then; with every agent they are refused'), adding little semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource (invite a person by email as a given role) and names the scoping target (all agents or agent_ids). It's clear what the tool does, but it never names an alternative sibling to route to — resend_invitation and cancel_invitation appear only in passing, so sibling differentiation is not 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?

Usage is only implied: the description covers the already-member case (409) and replacement of an open invitation, and mentions resendInvitation, but it never states 'use this when X, use resend_invitation when Y'. An agent must infer the routing rather than being told 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: result ordering ('newest first by when Mojeeb first saw each'), the exact inclusion trigger for an ad, and an explicit data-availability limitation (no spend or reach).

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 the definition, then filters, then cross-references. It is somewhat dense and long for a list tool, but each sentence carries distinct information (definition, ordering, exclusions, filters, related tools) rather than padding.

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

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

With no output schema, the description correctly compensates by enumerating what each returned ad contains (taps by channel, private replies, conversations, contacts, leads) and the ordering. 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%, so the schema already documents all five parameters including clamping, cursor semantics, and error codes. The description's mentions of active_since and search largely restate what the schema says, adding little parameter-level detail beyond the schema.

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

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

The description states a specific verb and resource ('List an agent's ads') and goes further by defining what an 'ad' means in this system (a customer tap on Messenger/Instagram/WhatsApp, or an Instagram comment on ad media). This distinguishes it cleanly from get_ad and from the various list_* 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 gives concrete filter conditions for active_since and search, and explicitly states scope exclusions (spend and reach are not available because Ads Manager is never read), which tells the agent when not to rely on this tool. It also cross-references listConversations' ad_id, but does not explicitly say when to use list_ads versus get_ad.

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/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the earliest-to-join-first ordering and the `can_open_agent` access-gating rule that determines assignability, plus the read-only assertion that confirms 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 core action, then layers sort order, the `can_open_agent` semantics, the rationale for listing non-openers, and the read-only note. Every sentence carries information an agent would otherwise have to guess at.

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

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

With no output schema, the description does useful work naming the returned concept (`can_open_agent`) and the id fields (`user_id`, `assigned_to`, `author_id`). It stops short of enumerating the full member payload, but it is complete enough to call and interpret 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 single `agent_id` parameter already documents its UUID format and the 404/403 failure modes. The description adds nothing further about the parameter, so the baseline 3 for full schema 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?

States a specific verb and resource (list teammates for an agent) and immediately scopes it to the whole organization in join order. It also distinguishes itself from mutation siblings by naming `inviteMember`, `updateOrganizationMember` and `removeOrganizationMember` as the tools that change the team.

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 for when to reach for this list: to resolve a lead's `assigned_to` or a note's `author_id` to a name, and to know who can be assigned work. It does not explicitly distinguish itself from the close sibling `list_organization_members`, leaving that 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 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 declare read-only, idempotent, non-destructive and closed-world behavior, so the description does not need to repeat safety traits. It adds useful behavioral context: results are newest first, omit links, and describe media metadata such as file names, types and sizes. It does not discuss pagination behavior, but that is partly covered in the 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 description is short, front-loaded and efficient. It leads with the core list operation, then immediately explains the return shape and the key alternative for obtaining links.

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 appropriately explains that each item describes media metadata without links and that results are newest first. It does not fully describe pagination or the overall response envelope, but the cursor and limit parameters are documented in the schema.

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

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

Schema description coverage is 100%, so all six parameters are already well documented. The description reinforces the main filters, especially `type`, `active` and `search`, but adds little meaning beyond what the schema already says, including the search length and case-insensitive matching.

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

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

The description states a specific verb and resource: list an agent's AI attachments. It scopes them as photos, albums, videos and documents, specifies newest-first ordering, and clearly distinguishes this from `getAttachmentMedia` by noting that this tool does not return links.

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

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

It gives clear usage context for filtering with `type`, `active` and `search`, and explicitly names `getAttachmentMedia` when links are needed. It does not distinguish from all sibling attachment tools such as `get_attachment`, but the media-link alternative is the most important routing clue.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds ordering ('in the order they were added') and the status lifecycle (pending -> sent/delivered/read/failed as WhatsApp reports it), plus failure_detail semantics. Useful context beyond annotations, though no pagination or permission details.

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 parts: a redundant first line repeating the title, then a dense, informative sentence. The body is front-loaded and every clause earns its place; the title repetition is the only minor waste.

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

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

No output schema, so the description must convey return values. It explains recipient status semantics, ordering, and failure_detail, but does not describe the full recipient object or pagination behavior (cursor/limit schema covers pagination). Adequate but leaves some return-shape gaps.

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

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

Schema description coverage is 80%; limit, cursor, agent_id, broadcast_id are documented in-schema. The status enum lacks a schema description, but the description compensates by explaining status filtering and failure_detail. Baseline is 3 with high coverage, raised to 4 for filling the status 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+resource: 'List a broadcast's recipients', and clarifies that each recipient's message status is included in insertion order. An agent can distinguish it from sibling list_broadcasts/get_broadcast 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?

Provides clear context for filtering: status narrows the list, e.g., to failed ones with failure_detail. However, it does not explicitly name when to use this tool versus get_broadcast or list_broadcasts, nor any when-not conditions. Clear context but 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: results are ordered newest-first and include broadcasts created via either the dashboard or the API, which the agent could not infer otherwise.

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, and the key scoping facts are front-loaded. Minor deduction for restating the title verbatim in the first line before adding new 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 read-only, cursor-paginated list tool with no output schema, the description covers ordering, scope and source, while pagination and error semantics live in the schema. What 'each with its counts' actually returns is left vague, but the annotations carry the safety profile.

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

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

Schema coverage is 75%, with limit, cursor and agent_id all well documented in the schema itself. The description only touches `status` ('narrows the list'), adding marginal meaning to an enum that has no schema description, so it does not materially extend the structured 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 specific verb (list) and resource (an agent's broadcasts) with scope, ordering ('newest first'), and origin ('sent from the dashboard or the API'). It implicitly separates from get_broadcast (singular retrieval) via the plural framing, but never names or contrasts a 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?

Usage is implied by the tool's name and the note that '`status` narrows the list', but there is no explicit when-to-use guidance, no mention of when to prefer get_broadcast or list_broadcast_recipients, and no stated prerequisites.

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

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

Annotations 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 declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: newest-first ordering, a hard cap of 50, the three source values (ai/dashboard/public_api) with their meaning, and the exclusion of ai_paused_until as not a real switch. That is genuine behavioral disclosure an agent could not infer.

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 lead sentence is front-loaded and every subsequent clause adds real information (limit, ordering, source taxonomy, exclusion). It is dense in a single block and the nested parenthetical for the `ai` source is slightly hard to parse, but nothing is wasted.

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

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

There is no output schema, so the description must describe the return shape — and it does: the value switched to, the origin with reason, the teammate, and the timestamp. Combined with the limit and ordering, an agent knows exactly what to expect from a call.

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

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

Schema description coverage is 100% and the two parameters carry their own 404/403 semantics, so the schema does the heavy lifting. The description adds nothing about agent_id or conversation_id, which is acceptable at full coverage but not above 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 (list) and resource (AI switch events for a conversation), and the scope is precise enough to separate it from resume_conversation_ai, which performs a switch rather than reporting one. An agent can tell what it retrieves 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?

"Use it to tell why a conversation's AI is off" gives an explicit triggering situation, and the closing note excludes the timed pause (ai_paused_until) as a non-case. It never names resume_conversation_ai as the alternative action tool, so the when-not side is only partially covered.

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