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

Annotations already mark the tool as not read-only and not destructive; the description adds that it consumes supplied links and returns a confirmation with resulting attachments. It does not go into duplicate handling or URL validation, but it gives enough behavioral context for normal use.

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 one-sentence purpose and then uses compact labeled sections for condition, alternative, prerequisite, example, and return. No filler.

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

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

For a two-parameter mutation with no output schema, the description covers the call prerequisites, example payload, and a return expectation. It leaves the return shape vague as {...}, but this is adequate for a confirmation-style response.

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

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

The schema describes links but leaves id as a bare string; the description fills that gap by pointing to list_messages results[].id. The example also anchors both parameters with concrete values.

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

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

The opening sentence names a specific action and resource: attach one or more link URLs to an existing message. The USE INSTEAD note explicitly separates it from create_message_share_link by contrasting producing a link vs consuming them.

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

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

USE WHEN states the intended trigger, USE INSTEAD names the sibling not to choose and why, and FIRST gives the prerequisite call to list_messages for the id. This removes ambiguity about when and how to invoke the tool.

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

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

Annotations only carry readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and delivers. It discloses the return shape, that new items start at status `todo`, the BAD_REQUEST error conditions, and the rule that assigned_to must be a valid user ID resolved via search_users, never a name. This is precisely the context an agent needs beyond static 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 organized into scannable labeled sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, ERROR) with the core statement front-loaded. Each sentence earns its place — the example, return shape, and error semantics are all necessary because no output schema exists. The length is justified for an 8-parameter mutation tool.

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

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

For a tool with no output schema, the description fully explains return values (RETURNS shape), initial status, failure modes, and prerequisite lookup routes (search_users, list_conversations, get_root_folders). workspace_id is the only parameter not explicitly addressed, but the schema documents it. An agent has everything needed to invoke this correctly on the first attempt.

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

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

Schema coverage is 75%, so the schema already documents six of eight parameters. The description adds cross-parameter constraints the schema cannot express: pass both container_type and container_id together, use source_message_id to 'link it to what prompted it', and resolve assigned_to via search_users. The compact example clarifies the minimal valid payload. Not a 5 because container_type enum values and workspace_id get no dedicated description, though the error section partially offsets the container 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?

Opens with a specific verb and resource — 'Create an action item' — and adds the optional attachment scope ('conversation or folder'). The USE INSTEAD clause names suggest_action_items_from_messages, the sibling most likely to be confused with this tool, so an agent can discriminate without opening the schema. This exceeds the baseline clarity of tools that rely on the name alone.

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

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

The description explicitly states WHEN to use it ('Recording a task') and WHEN NOT to ('USE INSTEAD: suggest_action_items_from_messages... instead of writing each one yourself'). It names the alternative tool, the condition that selects it, and even gives an example payload. Nothing 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 readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-read, non-destructive operation. The description adds valuable behavioral context: the either/or requirement for transcript/links, the threading behavior via parent_id, the expected return shape, and the specific BAD_REQUEST error condition. It doesn't fully disclose all side effects (e.g., notifications, TTS behavior), but the provided context goes well 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?

The description is compact and front-loaded. The core action is in the first sentence, followed by clearly labeled USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, and ERROR sections. Every sentence earns its place, and the formatting makes it easy for an agent to scan for the key decision points.

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

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

For a tool with 5 parameters, no output schema, and moderate complexity, the description covers the essential context: how to get the id, the threading mechanism, the either/or requirement, the return shape, and the primary error case. The from_message_id/from_message_type parameters are not explained in the description, but the schema provides some context. The description is complete enough for an agent to call the tool correctly in the common cases.

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

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

Schema coverage is 80%, and the description adds meaning beyond the schema. It clarifies that neither transcript nor links is individually required but at least one must be provided, which the schema descriptions also state but the description reinforces. It explains that parent_id is a message ID for threading, and that id comes from list_conversations. The from_message_id/from_message_type parameters are not explained in the description, but the schema provides some context for them. The description compensates well for the schema's ambiguity around the either/or requirement.

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

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

The description opens with a specific verb and resource: 'Post a message into an existing conversation, or reply in a thread.' It clearly distinguishes the tool from siblings by naming create_direct_message and create_voicememo_message as alternatives. The scope is precise: requires an existing conversation_id, and supports either a top-level post or a threaded reply via parent_id.

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 provides explicit USE WHEN, USE INSTEAD, and FIRST guidance. It tells the agent when to use this tool (has a conversation_id), when to use alternatives (create_direct_message for people not in a conversation, create_voicememo_message for standalone memos), and how to obtain the required id (from list_conversations). It also clarifies the parent_id threading behavior and the either/or requirement for transcript/links.

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

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

The description goes beyond the minimal annotations (readOnlyHint=false, destructiveHint=false) by disclosing the requirement for transcript or links, the error condition (BAD_REQUEST for invalid user ID or missing transcript/links), and the fact that a DM starts a separate thread. It also mentions the return shape and example, offering substantial behavioral context without contradicting 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 structured with clear sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, ERROR) that are all informative and directly relevant. Every sentence adds value, and it is front-loaded with the core action. No fluff 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?

Given the tool's complexity (6 parameters, nested object, enum, and no output schema), the description covers all essential aspects: usage context, prerequisites, example, return format, and error handling. An agent can confidently call this tool correctly based on the description alone.

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 meaning beyond the schema by clarifying that 'to.user_ids' comes from search_users and warning against passing display names as user IDs. It also highlights the transcript/links requirement, which is not immediately obvious from the schema alone.

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

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

The description states a specific verb and resource: 'Send a direct message to one or more people, by user ID or email.' It clearly distinguishes from the sibling tool by noting that a DM starts a separate thread rather than joining an existing conversation, making it unmistakable which tool to use.

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 explicitly states when to use this tool ('Reaching people outside an existing conversation') and when to use an alternative ('USE INSTEAD: create_conversation_message when a conversation already exists'). It also provides a prerequisite step (calling search_users to obtain user_ids), which is valuable guidance for the 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 indicate readOnlyHint=false and destructiveHint=false, so the mutation is implied. The description adds value by specifying that it returns the created folder 'same shape as get_folder,' which is beyond the annotations. It also clarifies the nesting behavior via parent_folder_id. This provides useful behavioral context beyond what annotations declare.

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 compact yet structured with clear section markers (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS). Each sentence serves a purpose: purpose, usage context, alternatives, prerequisite, example, and return shape. No redundancy or fluff, and the most critical information (purpose) is front-loaded.

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

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

For a create operation with 4 parameters and no output schema, the description covers all necessary aspects: what it does, when to use it, what to use instead, how to obtain a required parameter, an example payload, and the return format. There are no missing pieces an agent would need to correctly invoke the tool.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds an example with a sample value, emphasizes required fields, and clarifies parent_folder_id for nesting. This goes beyond the schema's dry descriptions, providing concrete usage context. The example directly maps to the parameter structure.

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 explicitly states 'Create a folder in a workspace, optionally nested under another.' This is a specific verb and resource, and the mention of optional nesting distinguishes it from sibling tools like move_folder and delete_folder. It clearly defines what the tool does without ambiguity.

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

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

The description provides explicit usage guidance: 'USE WHEN: Organising memos' and 'USE INSTEAD: move_folder to relocate a folder that already exists.' It also instructs to call get_workspaces_basic_info first to obtain workspace_id. This clearly tells the agent when to use this tool and when to use an alternative, leaving no inference needed.

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 only say readOnlyHint=false and destructiveHint=false, so they don't disclose much beyond 'this writes'. The description fills the gap by explaining what is created, what the `id` means for other tools, what fields can be returned, and what happens on a BAD_REQUEST with two specific causes. It also discloses that the full payload is much larger and suggests response_fields as a mitigation.

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 organized with clear section labels (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW, ERROR) and front-loads the core purpose. Each section earns its place by conveying a distinct operational fact; despite the length, there is no filler or repetition of schema 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?

For a 7-parameter tool with no output schema, this description is remarkably complete: it explains prerequisites, alternatives, return shape, how to obtain dependent IDs, optional response narrowing, and error conditions. An agent can correctly select and invoke this tool using only the description plus 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?

Though schema coverage is 100%, the description adds critical parameter behavior: `message_id` is only needed when `share_type` is "forward", `shared_message_id` comes from `list_messages` results[].id, and `response_fields` is a dot-path allowlist for shrinking the response. The example ties required parameters together, and the error section clarifies invalid parameter combinations. This goes well beyond the raw schema 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 first sentence names the exact verb and resource: "Create a shareable link to an existing message ... and get the URL back." It clearly distinguishes this tool from siblings like `add_attachments_to_message` by contrasting sharing a Carbon Voice message outward with attaching an external URL. The purpose is unambiguous and specific.

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 is exemplary in routing: it says when to use `share_type: "link"` vs `"forward"`, names the alternative tool `add_attachments_to_message` and when NOT to use it, and tells the agent to call `list_messages` first for `shared_message_id`. It even gives a concrete JSON example, leaving no ambiguity about invocation.

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

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

The description adds substantial behavioral context beyond the minimal annotations: audio_url overrides transcript, status is often "processing" at first, and both INVALID_AUDIO_URL and BAD_REQUEST error conditions are fully explained. This gives the agent a reliable model of what happens when the tool is invoked.

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 longer than average but every labeled section (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, ERRORS) carries useful information. Key selection criteria are front-loaded before return and error details.

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

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

Given no output schema, the description compensates with a return shape and the note that status is often 'processing'. It also covers the three mutually exclusive input modes via the BAD_REQUEST error, file destination options, and common failure modes. The schema covers links and formats, so nothing critical is missing 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%, so the input schema already documents all five parameters well. The description mostly restates schema semantics, such as "audio_url wins over transcript" and the 2-5000 character limit, without adding meaning beyond what the schema already provides.

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: "Create a voice memo, either from text (spoken via text-to-speech) or from an audio file at a URL." It also differentiates this tool from the sibling tools by explicitly noting that a voice memo is "standalone and lives in a folder or workspace."

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 has explicit USE WHEN guidance for transcript vs audio_url vs folder_id/workspace_id, and a USE INSTEAD section naming create_conversation_message and create_direct_message with the reason. It also gives a concrete example, leaving little 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 mark destructiveHint: true, and the description adds meaningful context beyond that: deletions are permanent ('cannot be undone') and the tool returns a deletion confirmation. This gives the agent a fuller behavioral model than the annotation 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?

The description uses a labeled structure (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS) that front-loads the key decision and keeps each section purposeful. Every sentence earns its place without excess.

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

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

For a simple one-parameter destructive tool with annotations already covering the danger profile, the description covers the usage context, filter condition, id origin, example, and return value. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0% (the id parameter has no description), but the description fully compensates by explaining where the id comes from (list_my_action_items, field results[].id), instructing to call that first if needed, and providing a concrete example. No gap remains for the single parameter.

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

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

The description states a specific verb and resource ('Permanently delete an action item') and immediately clarifies scope ('should not exist at all'), distinguishing it from the related set_action_item_status sibling. An agent can tell exactly what this tool does and how it differs from completing an item.

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?

Contains explicit 'USE WHEN' and 'USE INSTEAD' guidance, naming the alternative tool (set_action_item_status with `done`) and the condition that selects it. It also warns to prefer deletion only for spurious items, leaving no inference required.

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 destructiveHint=true annotation, the description discloses that the deletion cascades to nested folders and messages, cannot be undone, and is easy to underestimate. It also states the return value is a deletion confirmation. No contradiction with 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?

Structured with labeled sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS) that front-load critical constraints before the example. Every sentence contributes actionable information with no filler.

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

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

For a destructive cascade tool with one parameter and no output schema, the description covers invocation trigger, alternatives, id provenance, an example, and the return type. The agent has everything needed to call the tool correctly and safely.

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 0% schema description coverage, the description fully compensates: it states the id comes from get_root_folders (field results[].id), instructs to call that first if needed, and provides an example {"id":"folder-abc"}. This is more meaning than the bare 'id: string' schema provides.

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

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

States a specific verb and resource: 'Permanently delete a folder, including every nested folder and all their messages.' The scope of deletion is explicit, distinguishing it from siblings like move_folder and get_folder.

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 explicit USE WHEN ('Only when the whole subtree should be destroyed') and USE INSTEAD sections naming move_folder and move_message_to_folder as alternatives. Also instructs to check total_nested_messages_count via get_folder before calling, leaving no ambiguity about when to invoke 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=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context by listing the returned fields (including optional ones) and explicitly noting that the list tools already return the same per-item fields, implying a redundant call is unnecessary. This goes beyond the annotation baseline without contradicting 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?

The description is tightly organized with clear semantic labels (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS). The purpose is front-loaded, and every line carries functional information. There is zero fluff; each section earns its place by guiding the agent's decision.

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-ID fetch tool with no output schema, the description provides everything an agent needs: the source of the ID, the return shape, the differentiation from siblings, and an example. The complexity is low, and the description fully covers the decision and invocation path. No essential information 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 schema covers one of two parameters (response_fields has a description), leaving id without schema-level documentation. The description compensates by explaining where id comes from (list_my_action_items results[].id) and gives an example value. However, it does not mention the response_fields parameter at all, which is a minor gap given the schema already documents it. Overall, the description adds meaningful meaning to the critical id parameter.

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

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

The description opens with a precise verb-object pair, 'Get one action item by its ID, with full detail,' and immediately distinguishes this tool from the list siblings by stating it operates on a single ID. The scope is explicit and the differentiation is clear without needing to inspect sibling 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?

The description uses labeled sections (USE WHEN, USE INSTEAD, FIRST) to give explicit usage context. It names the alternatives (list_my_action_items, list_action_items), states when to choose them (no ID yet), and warns that a follow-up call is usually wasted because those already return the same fields. This is exceptionally clear routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds meaningful behavioral context beyond that: the return format, the fact that an empty array is returned if no data exists, and a warning that the full payload is much larger and can be shrunk with response_fields. This gives the agent a good sense of what to expect, though it doesn't explicitly explain the date/direction pagination mechanics (those are in the schema but not described 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?

The description is tightly organized with labeled sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW) and every sentence contributes. The core purpose is front-loaded, and the example is compact. There is zero 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?

Given the tool is a simple read-only retriever with no output schema, the description fully covers what an agent needs: what it does, when to use it, how to narrow results, what the return looks like, and a performance tip. The absence of a documented output schema is mitigated by the explicit RETURNS section. It is complete 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 coverage is 86%, so the schema already documents most parameters. The description adds value by explaining the combined use of prompt_id, message_id, and channel_id to narrow results, and by clarifying that response_fields is an allowlist to shrink the payload. The example demonstrates a realistic usage. This exceeds the baseline for high schema coverage.

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

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

The description opens with a clear, specific verb-resource statement: 'Retrieve AI Action results that were generated previously.' It immediately distinguishes itself from run_ai_action by noting it only reads existing output, and it lists the narrowing fields. This makes the tool's purpose unambiguous and differentiates it from siblings like run_ai_action and summarize_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?

The description provides explicit 'USE WHEN' and 'USE INSTEAD' sections, telling the agent exactly when to pick this tool (when existing output is wanted) and when to pick alternatives (run_ai_action or summarize_conversation for fresh generation). It also gives a concrete example and notes that an empty array is returned if nothing exists, which sets expectations clearly.

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

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

Annotations already declare readOnlyHint and destructiveHint, and the description adds what the response contains and explicitly states it returns neither participant lists nor messages. It also sketches the return shape; a small gap is that it doesn't mention response_fields behavior, but the schema covers that.

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?

Seven short labeled sections each add distinct value: operation, trigger, alternatives, id source, example, return shape. No filler, and the key purpose is front-loaded.

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

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

For a single-object read tool, everything needed to call it correctly is present: when, alternatives, id provenance, example JSON, return shape, and annotations for safety. The output schema is absent, but the RETURNS field compensates, and the optional response_fields parameter is documented in the input 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?

id is just a string in the schema; the description adds its meaning (conversation_id), its provenance (list_conversations results[].id), and an example. response_fields is already described in the schema, so the description does not need to repeat it; with 50% schema coverage this is adequate compensation.

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?

Opening line names the exact operation: get one conversation by ID, and states the payload category (full metadata). The USE INSTEAD section explicitly contrasts with get_conversation_users and list_messages, so an agent can distinguish it from the nearest 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?

USE WHEN gives a concrete trigger condition (having a conversation_id and needing description, visibility, owner, workspace name). USE INSTEAD routes to the right sibling for participants/messages, and FIRST tells where the id comes from, making the decision and call sequence explicit.

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

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

Annotations already convey that the tool is read-only and non-destructive. The description adds useful behavioral context beyond this: it returns an array of user objects, states that the full payload is much larger, and recommends narrowing fields to avoid 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?

The capitalized micro-headings create a scannable structure, and every sentence earns its place: when to use it, what it returns, how to get the input, an example, and a performance tip. Nothing is redundant with the schema or annotations.

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

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

For a two-parameter read-only tool with no output schema, the description covers everything an agent needs: purpose, input provenance, response shape, and field-narrowing guidance. It is complete without requiring the agent to inspect siblings or infer behavior.

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

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

Schema description coverage is only 50% (the `id` parameter is undocumented). The description compensates by explaining where `id` comes from (`list_conversations` field `results[].id`), giving a concrete example, and showing exactly how to use `response_fields` to shrink the response.

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

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

The description opens with a specific verb and resource: "List the people in a conversation." It also distinguishes itself from the sibling `search_users` by emphasizing that it is scoped to one conversation, making its purpose 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?

The USE WHEN section states the exact use cases, and USE INSTEAD names the alternative tool and the condition selecting it. The FIRST guidance even tells the agent to call `list_conversations` first and where to find `id`, which is precise routing information.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: the response payload is LARGE with unbounded arrays and an open settings map, and it explains the NARROW mechanism to mitigate this. This is genuinely useful for an agent deciding whether to invoke and how to shape the request.

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 tightly structured with labeled sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW) that are each a single line or two, no filler, and the most critical scoping information is front-loaded. Every sentence 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 no-required-parameter read-only tool, this description is complete: it explains the return shape (albeit without a formal output schema, it gives a useful sketch), warns about response size, provides an example call, and routes to alternatives when appropriate. Nothing an agent needs to call it correctly is missing.

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

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

The schema description fully documents response_fields (dot-path allowlist, example, omit for full payload). The description reinforces this with a concrete recommended list (['user.user_guid','user.first_name','user.email_txt','user.workspace_guids']) and warns about the full payload size, adding practical value 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-resource pair ('Get the calling user's own identity, workspaces and settings') and explicitly distinguishes itself from get_user (for others) and get_workspaces_basic_info (smaller response). This makes the tool's purpose unambiguous and separable from siblings without needing to inspect 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 provides explicit USE WHEN conditions (establishing identity, finding workspace IDs before workspace-scoped calls) and USE INSTEAD guidance naming two alternatives with the exact condition that selects them. This gives an agent clear routing rules, leaving nothing to inference.

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

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

The description discloses a non-obvious and potentially dangerous behavioral quirk: both date and direction are silently ignored unless include_first_level_tree is true. It also explains that this tool returns only structure and counts, not message contents, and includes a return shape with optional fields. The annotations already declare readOnly and non-destructive, so no contradiction exists and the extra caveat meaningfully adds transparency.

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 well-structured with clear labels and front-loaded purpose, then chunked into usage, alternative, prerequisite, example, and return sections. It is somewhat dense and includes a slightly cryptic phrase ('unless you do' and 'upstream only documented that caveat on date'), but overall every major section earns its place and improves usability.

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 compensates by providing a return shape and clarifying optional fields. It also covers the prerequisite call, the mutation-free read-only nature, the subfolder behavior, and the sibling distinction. For a 5-param tool with one required param, no output schema, and only read-only annotations, this is a complete and well-rounded definition.

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%, so the baseline is already fairly high. The description adds important meaning for the undocumented id parameter by identifying its source and exact extraction path (get_root_folders results[].id), and it includes a concrete example. It mostly restates the schema for date, direction, and response_fields, but the id guidance plus example lifts it 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?

The description states a specific action and resource: retrieving one folder's metadata, with an optional subfolder tree. It explicitly names get_folder_with_messages as the alternative and clarifies this tool returns structure and counts only, so the agent can distinguish it from a related sibling.

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

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

It gives explicit 'USE WHEN' context for inspecting a folder, 'USE INSTEAD' guidance for get_folder_with_messages, and a 'FIRST' instruction to call get_root_folders for the id. This gives clear routing between alternatives and prerequisites, which is exactly what an agent needs to decide when to call 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?

The description discloses non-obvious behavior beyond the read-only annotations: nested folders are not walked, date filtering and paging are unsupported, and the full payload is much larger than the narrow response. It also states the exact return shape, which is valuable since no output schema exists.

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 structured with clear labels and every block adds distinct value: purpose, when, alternatives, dependency, example, return shape, and response narrowing. It is longer than average but earns its length by front-loading the most important 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?

Given only two parameters, no output schema, and safe read-only annotations, the description covers everything needed to invoke the tool correctly: id provenance, response shape, lack of paging/filtering, and a recommended narrow response. No critical invocation context 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?

With only 50% schema coverage, the description compensates well: it explains where id comes from (get_root_folders results[].id) and gives a concrete response_fields example while warning that the full payload is much larger. This adds meaning the schema does not provide for id and goes beyond the schema's generic response_fields description.

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

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

The description opens with a specific verb-resource pair: 'Get a folder together with the messages stored directly in it.' It also distinguishes itself from sibling tools by clarifying that only messages at that folder's own level are returned and nested folders are not walked.

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

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

It explicitly provides USE WHEN, USE INSTEAD with named alternatives (get_folder, list_messages), and the conditions that select each. It also tells the agent to call get_root_folders first to obtain the id, which is essential invocation 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 and destructiveHint=false, so the description doesn't need to repeat safety. It adds critical behavioral detail: 'fields' ADDS data rather than narrows, and 'response_fields' narrows. It also discloses the return shape with optional fields, giving agents a clear expectation of the response beyond what annotations 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?

The description is well-structured with labeled sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS) that front-load the purpose and usage. Each sentence adds value, from the example to the return format, without redundancy. It is longer than minimal but every line earns its place by preventing common mistakes.

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

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

Given the absence of an output schema, the description provides a return shape with optional fields. It covers parameter semantics, usage workflow, and alternatives. It does not mention error handling, but for a single-message retrieval with read-only semantics, the provided information is sufficient for an agent to call it correctly. The language parameter is covered by the schema, so no gap remains.

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 description explains the id parameter's provenance (from list_messages), clarifies that 'fields' adds related records (listing possible values), and distinguishes it from 'response_fields' with an example. It covers the parameters more richly than the schema alone, especially for 'id' which lacks a schema description, thus compensating for the 75% coverage.

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

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

The description states a specific verb and resource: 'Get one message by ID', and immediately distinguishes it from list_messages by clarifying it retrieves a single message. It also clarifies the optional expansion with 'fields', so the purpose is unambiguous and distinct from 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 provides when to use ('USE WHEN: You have a message ID') and when not to use ('USE INSTEAD: list_messages when you do not have an ID, or need several messages'), including a rationale about wasted calls. It also gives a 'FIRST' instruction on obtaining the ID from list_messages, covering the typical workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: instructs to check revoked_at and end_access_at for validity, notes that the return shape matches create_message_share_link, mentions the full payload is large and suggests response_fields to narrow it, and explains the NOT_FOUND error condition. This goes beyond annotations without contradicting them.

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

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

The description is longer than average but highly structured with clear headers (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW, ERROR). Every section earns its place and adds actionable detail. Slight redundancy (e.g., share_link_id source mentioned both in schema and description) but not wasteful.

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

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

For a read-only lookup with two parameters and no output schema, the description covers the use case, the error case, the return shape, and performance optimization. It gives an example and explicitly handles the NOT_FOUND scenario. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for both parameters. The description reinforces the source of share_link_id (from create) and gives a concrete example, plus a NARROW section that explains when and why to use response_fields. This adds practical usage nuance beyond the schema's 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 opens with a specific verb+resource: 'Look up an existing message share link by its ID, including the message behind it.' It clearly distinguishes this from siblings: it reads existing links (vs create_message_share_link) and returns the message payload (vs get_message). No ambiguity.

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

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

Explicit USE WHEN (have a share link ID and want its URL/access settings/validity), USE INSTEAD (create for new, get_message if you have the message ID), and FIRST guidance (share_link_id comes from create_message_share_link). This fully routes the agent to the correct tool and 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 indicate read-only and non-destructive; the description adds the 10-message cap, lack of paging/total, and filter limitations. It does not define the ordering criterion behind 'recent' or error behavior, but covers the important operational boundaries.

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?

Labeled USE WHEN, USE INSTEAD, EXAMPLE, and RETURNS sections make each point scannable and front-loaded. No wasted sentences; every clause adds decision-relevant information.

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

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

With no output schema, the RETURNS section supplies the response shape and explicitly disclaims paging/total. Between annotations, schema, and description, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema already documents all three parameters at 100% coverage, so baseline applies. Description reinforces that conversation_id and language are the only filters and provides a usage example, but adds little per-parameter semantic 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?

Clearly states a specific verb+resource: retrieving up to 10 most recent messages with conversation, creator, and labels. Distinguishes from list_messages by count and pre-joined data.

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 labels USE WHEN and USE INSTEAD, naming list_messages as the alternative and listing conditions (more than 10, date range, paging, other filters). This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: the result is not paginated, it returns the complete set, and the full payload is much larger. It also shows how to narrow output with response_fields, which goes beyond annotation data.

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

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

The description is well-structured with clear USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, and NARROW sections. Every sentence contributes actionable guidance, and the most important usage details are front-loaded.

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

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

Despite having no output schema, the description documents the return shape explicitly, including optional fields and non-pagination. For a 6-parameter read-only list tool, this is a complete and self-sufficient definition.

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?

Input schema covers all parameters at 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete example, clarifying type's allowed values, explaining include_all_tree's effect, and documenting response_fields behavior with an example allowlist.

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

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

States a specific verb and resource ('List the root folders of a workspace') and scopes by folder type. The USE INSTEAD section explicitly names get_folder and get_folder_with_messages as distinct alternatives, so sibling differentiation is strong.

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 explicit USE WHEN conditions ('Orienting in the folder tree, or finding a folder_id'), states that type is required, and names alternatives with the conditions that select them. This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the tool requires an explicit ID and will not default to the caller, the full payload is much larger, and response_fields can shrink it. These details go beyond the annotations and help an agent manage expectations about output size and ID requirements.

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?

Although longer than two sentences, every line earns its place. The description uses scannable headers (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW) and front-loads the core purpose. No filler or redundant content appears, and the structured format makes it easy for an agent to parse quickly.

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 provides a return shape ('{id, first_name, last_name?, languages, voice_gender, workspace_ids, workspace_roles, user_type, created_at, ...}') and explains how to narrow it. It also covers the required parameter's provenance and an example. For a read-only get tool, this is enough for an agent to invoke it correctly and interpret results without needing additional documentation.

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% (the id property has no description), and the description fully compensates. It explains that id comes from search_users' id field, gives a concrete example ('user-abc'), and interprets response_fields as a 'Dot-path allowlist to shrink the response' with examples. Both parameters gain semantic meaning beyond the raw 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 opens with 'Get a user's full profile by ID' and enumerates the fields covered ('names, languages, voice settings, workspace roles'), which clearly identifies the verb, resource, and scope. It also names its siblings explicitly under 'USE INSTEAD', distinguishing itself from search_user/search_users and get_current_user, so an agent can select it correctly 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 'USE WHEN', 'USE INSTEAD', and 'FIRST' sections provide explicit conditions for use, alternatives to prefer, and the required precursor call to search_users. It even advises on narrow response fields with 'NARROW', giving concrete guidance on efficient invocation. This is exemplary when-to-use vs when-not-to-use 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 and destructiveHint=false, but the description adds useful behavioral details: 'Takes no arguments', 'Nothing else, and no paging', and emphasizes minimal cost. These go beyond the annotations and fully disclose the operation's scope.

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

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

The description is tightly structured with USE WHEN, USE INSTEAD, EXAMPLE, and RETURNS sections. Every sentence adds value, the core purpose is front-loaded, and there is zero fluff.

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 no-param read-only list tool, the description fully covers usage context, output shape, and exclusions (no paging). It also names the alternative, making it self-contained. Nothing an agent needs to call it correctly is missing.

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

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

With zero parameters and 100% schema coverage, the description explicitly confirms 'Takes no arguments', removing any doubt. This is more than the baseline for zero-param tools.

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 clearly states the action ('List'), the resource ('every workspace you belong to'), and the exact output scope ('as id and name only'). It differentiates from siblings by focusing solely on workspace ID/name retrieval, and even names the alternative get_current_user.

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 explicit 'USE WHEN' context (cheapest way to resolve workspace name to ID) and an explicit 'USE INSTEAD' alternative (get_current_user) with trade-off rationale (response size). This leaves no ambiguity about when to choose this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is safe. The description adds valuable context: filtering by status or assigned_to (with 'null' for unassigned), the RETURN format matching list_my_action_items, and a performance tip to use response_fields to shrink payload. It doesn't clarify pagination behavior beyond cursors, but annotations cover safety, and the description adds meaningful usage behavior.

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

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

The description is well-structured with clear sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW). It's front-loaded with the core purpose and uses bold headings for scannability. Every line adds value—no fluff, and it maintains brevity despite the density.

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

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

Given the tool's complexity (10 params, multiple container types), the description covers all essential aspects: how to get container_id, how to filter, pagination cursors, return shape, and optimization tips. The output schema is absent, but the description explicitly states the return format. It's complete for an agent to call correctly without external lookup.

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 schema coverage at 60%, the description compensates by explaining key non-schema-covered semantics: container_type and container_id are identified as the required pair, with specific values for container_type, and it notes that a conversation id is not a folder id. It also clarifies the use of the 'null' string for assigned_to filtering, which is in the schema but reinforced. The description doesn't cover all parameters, but adds significant meaning beyond the schema.

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

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

The description clearly states the tool lists action items for a specific container, with explicit examples of container_type values (channel, folder, home). It distinguishes itself from the sibling list_my_action_items by specifying scope (one container vs. all assigned to user). The verb 'list' and resource 'action items' are specific and 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?

The description gives explicit 'USE WHEN' and 'USE INSTEAD' instructions, naming the alternative tool list_my_action_items and the condition for choosing it. It provides clear prerequisites ('FIRST' sections) explaining how to obtain container_id for each container type, and includes an example call. This is comprehensive routing 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 and destructiveHint=false, and the description is consistent. It adds valuable behavioral context by detailing the return structure (array of specific fields) and warns that the full payload is much larger, advising response_fields to narrow it. This goes beyond annotations and helps the agent understand response size and how to control 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?

The description is well-structured with clear sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW) and every sentence adds essential information. It is front-loaded with the core purpose and routes to alternatives early. No redundancy or fluff.

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

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

For a simple list tool with no output schema, the description fully covers the return format, filtering options, example usage, and performance guidance. It leaves nothing an agent needs to call the tool correctly, including how to handle the potentially large payload.

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 67%, and the description compensates by explaining owner_type (which only has an enum in the schema) with the meaning of each value (user, workspace, system) and providing an example. It also explains the purpose of response_fields as a dot-path allowlist to shrink the response. Workspace_id is already documented in the schema, so the description adds value for the remaining parameters.

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

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

The description clearly states the tool lists AI Actions (Prompts) and explicitly distinguishes it from get_ai_action_responses, which retrieves already-generated results. It provides a specific verb-resource pair and names the sibling it is not, making selection unambiguous.

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

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

It provides explicit when-to-use guidance: before calling run_ai_action or summarize_conversation to find a prompt_id, and to show available AI Actions. It also gives a clear alternative (get_ai_action_responses) and explains the filtering by owner_type with an example, leaving no inference required.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: the 6-month retention window, implicit participant semantics, filter AND-ing, the meaning of unfiltered_count, and the absence of paging. These details are critical for correct invocation and interpretation.

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 well-structured with clear section labels (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS) and front-loads the core purpose. Despite its length, each sentence contributes operational guidance rather than repetition, and the format makes it easy for an agent 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?

The description fully covers the tool's complexity: return shape, type enum, count semantics, edge cases (0 of 47 vs 0 of 0), and when to ask the caller for clarification. Since there is no output schema, the description correctly carries the responsibility of explaining the response and filtering behavior.

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

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

Although schema description coverage is 100%, the description adds meaning the schema alone does not fully convey: the agent is always an implicit participant, passing the caller's own ID silently breaks filtering, and user_ids must be resolved via search_users before use. It also supplies a concrete JSON example that models correct parameter usage.

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

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

The first sentence states a specific verb ('List'), resource ('your conversations'), time scope ('last 6 months'), and optional filters. It also explicitly contrasts itself with get_conversation, saying it returns only id, name, workspace_id and type, which makes its identity unambiguous 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 provides explicit 'USE WHEN' and 'USE INSTEAD' guidance, names the alternative tool, and explains the exact conditions for choosing between them. It also instructs the agent on what to do when filters produce multiple matches or when unfiltered_count suggests a nonexistent 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?

Beyond the readOnlyHint annotation, the description discloses pagination behavior (skip/limit, not cursors), the presence of total_unread, the response shape, and the large payload cost with a NARROW recommendation. This adds meaningful 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 well-structured with labeled sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW), front-loads the core purpose, and every section earns its place. It packs substantial routing and response information into a compact, scannable format.

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?

Despite having no output schema, the description explains the return structure, unread count, pagination model, and payload optimization. Combined with a fully described input schema, it gives an agent everything needed to select and invoke this tool correctly.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds value by telling agents to pass category: 'mentions' for mention queriesтся and to pass response_fields ['results','total_unread','total_results'] to shrink the payload, which is practical guidance beyond schema definitions.

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

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

The description opens with a specific verb and resource: 'List your inbox notifications, with a total unread count.' It clearly distinguishes itself from message-search siblings by emphasizing notification records rather than messages, so an agent can tell it apart from search_message_ids and search_messages_by_heard_status.

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 WHEN' explicitly maps common user intents like 'what did I miss' to this tool, including the category parameter for mentions. 'USE INSTEAD' names the exact alternative tools and the conditions under which they should be preferred, giving agents clear routing 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 readOnlyHint=true/destructiveHint=false, the description discloses the 183-day max date span, that user_ids filters by SENDER (matched against creator_id, not participants), the pagination contract ('Page on has_next_page/total — do not guess'), and that the full payload is much larger, warranting response_fields narrowing. No contradiction with 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?

Longer than typical but every section earns its place given 12 params and ~39 siblings. The sectioned format (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, NARROW) is scannable and front-loaded with the core purpose. Slight density cost, hence not 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?

No output schema exists, and the description compensates fully by inlining the return structure, pagination guidance, and payload-shrinking advice. Covers setup prerequisites, usage routing, and behavioral constraints for a complex 12-param tool with zero required parameters.

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 baseline is 3. The description adds genuine value on top: the user_ids semantics (filters by sender/creator_id, requires IDs from search_users, resolve conversations for the WITH-someone case), the origin of workspace_id, and the response_fields dot-path usage. These go beyond what the schema states, earning 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?

Opens with a specific verb and resource plus explicit filter dimensions ('date, conversation, folder, workspace, creator or language'). Differentiates from siblings by naming get_recent_messages and search_message_ids and what distinguishes them. The USE INSTEAD section preempts the agent picking the wrong sibling.

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

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

Provides explicit USE WHEN / USE INSTEAD routing: get_recent_messages for a quick capped look (hard-capped at 10, no paging) and search_message_ids for filters this cannot express (notified state, mentions, labels). Also instructs FIRST to resolve workspace_id from get_workspaces_basic_info, covering the prerequisite an agent would otherwise have to 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 declare readOnlyHint=true and destructiveHint=false, and the description adds rich context: return payload shape, pagination loop with has_more/next_cursor/starting_after, status value meanings, and the null assigned_to caveat. It also gives a concrete example, going well beyond structured 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?

Although long, the description is structured with clear labels (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW) and front-loads the core purpose. Every section contributes actionable guidance with no filler.

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

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

With no output schema, the description fully specifies return fields, pagination behavior, and filtering semantics. It covers the main use case, common edge case (null assigned_to), and performance tip, making it self-sufficient for correct invocation.

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

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

Schema coverage is 71%, and the description compensates by explaining status enum values (todo, suggested, done), pagination via starting_after, and response_fields narrowing with a performance rationale. It doesn't repeat what schema already says about date/limit/direction, but adds meaningful value.

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 your action items across every conversation and folder', with clear inclusion criteria (assigned to you PLUS unassigned ones you created). It also distinguishes itself from list_action_items by scope, so an agent can tell them apart.

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 provides USE WHEN and USE INSTEAD sections. It tells the agent when to call this tool (what do I owe / what is on my plate), warns about null assigned_to semantics, and names list_action_items as the alternative for a specific conversation/folder.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context: the exclusivity constraint (one destination, not both), the self-nesting error condition, and the return shape. It doesn't detail side effects on child folders, but the provided context is strong.

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 compact, front-loaded with the core action, and every section earns its place: use-when, alternatives, prerequisite, example, and error handling. No filler or repetition.

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

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

For a 3-parameter mutation tool with no output schema, the description covers the key decision (which destination parameter), the prerequisite call, the error case, and the return shape. An agent has enough to invoke it correctly without additional lookups.

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 67%, and the description compensates by explaining the semantic difference between `folder_id` and `workspace_id`, including the 'one or the other, not both' rule. It also clarifies where `id` comes from. This adds meaning beyond the bare schema 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 ('Move a folder into another folder, or up to a workspace root') and clearly distinguishes it from siblings like `update_folder_name` and `move_message_to_folder`. The purpose is unambiguous and immediately actionable.

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 'USE WHEN' section explicitly states when to use the tool, and 'USE INSTEAD' names alternatives with conditions. It also provides a 'FIRST' prerequisite and an example, giving an agent complete routing and sequencing 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 indicate destructiveHint=true, and the description enriches this by detailing the mutation constraints: only certain message types, creator requirement, type matching, and rejection of both/neither destination. It also explains the return value and common error cause with remediation steps. This goes well beyond the annotation, which is appropriate for a destructive action.

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

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

The description is well-structured with clear headers (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, ERROR) and every sentence serves a purpose. It is concise despite covering multiple aspects, with no redundancy. The action is front-loaded and the format aids agent parsing.

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

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

For a 3-parameter mutation tool with no output schema, the description is remarkably complete. It covers prerequisites, how to obtain a required ID, the error condition and how to diagnose it, and the return value. Given the complexity and sibling interactions, nothing essential is missing.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds an example showing the correct combination and a FIRST note about where message_id comes from (list_messages), which helps clarify the practical semantics of the parameters. This additional context justifies 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?

The description clearly states the action: moving a message into a folder or out to a workspace. It distinguishes itself from siblings by naming move_folder and create_voicememo_message as alternatives. The specific constraints on message types and destination rules make the purpose 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?

Explicit USE WHEN and USE INSTEAD sections provide clear conditions for this tool vs alternatives. It states when to use (filing a memo), prerequisites (voicememo/prerecorded, creator, type match), and the exactly-one-destination rule. This is exemplary routing 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description does not contradict these; it adds useful behavioral context: the return shape (`RETURNS: {id, prompt_id, message_ids, ...}`), that output is in `responses[]` per language, and a specific error condition (BAD_REQUEST) with guidance not to retry with the same IDs. This adds value beyond the annotations without overloading.

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 structured with clear sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, ERROR), which makes it scannable and front-loads the core purpose. It is somewhat long but every section adds information an agent needs; no filler. The example and error handling justify the length.

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

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

For a tool with 7 parameters, 2 required, and no output schema, the description covers the return format, error conditions, and where to obtain IDs. It also hints at optional parameters like `channel_id` and `workspace_id` through the return shape, but the schema already covers those. The description is sufficient for an agent to call it correctly without additional lookups.

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 each parameter already has a description. The tool description adds extra meaning by explaining where to source `prompt_id` and `message_ids` (from `list_ai_actions` and `list_messages`), providing a concrete example with all fields, and clarifying the default behavior of `language`. This goes beyond the schema's basic 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 ('Run an AI Action') against a specific resource ('one or more specific messages'), and explicitly differentiates itself from the sibling tool `summarize_conversation` by naming it and the condition that selects it. This makes the purpose unmistakable and distinguishes it from alternatives without needing to inspect 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?

The description provides explicit USE WHEN and USE INSTEAD directives, naming `summarize_conversation` as the alternative for whole-conversation summaries. It also gives FIRST instructions for obtaining `prompt_id` and `message_ids` from `list_ai_actions` and `list_messages`, which is actionable guidance for an agent. This fully covers when to use this tool versus 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, and the description does not contradict these. It adds substantial behavioral context beyond the annotations: the exact NOT_FOUND error semantics (nonexistent, revoked, or expired links), remediation steps (create a fresh link or verify with get_message_share_link), and the response envelope shape. This is precisely the kind of failure-mode and recovery disclosure an agent needs.

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

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

The description is longer than average but highly structured with scannable prefixes (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, ERROR). Every sentence earns its place: purpose, routing, prerequisites, an example, return shape, and error handling. There is no filler or repetition of schema content.

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

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

For a 4-parameter tool with no output schema, the description is complete: it covers what the tool does, when to use it vs. the sibling, prerequisites and their source calls, a worked example, the return format, and error conditions with remediation. An agent has everything it needs to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying provenance for the two required parameters: `share_link_ids` comes from `create_message_share_link` (field `id`) and `prompt_id` from `list_ai_actions` (field `id`), plus a concrete example JSON. It doesn't add param-level detail for `language` or `response_fields`, but the schema already covers those adequately.

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

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

The first sentence states a specific verb+resource: 'Run an AI Action (Prompt) against one or more shared messages, addressed by share link ID.' This precisely identifies what the tool does and immediately differentiates it from the sibling `run_ai_action` by establishing the share-link addressing mechanism.

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 provides explicit routing: 'USE WHEN' states the trigger condition (having share link IDs), and 'USE INSTEAD: run_ai_action if you have the message IDs directly' names the alternative and the decision rule. The 'FIRST' instructions also clarify prerequisite calls. Nothing 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 readOnlyHint and non-destructive behavior. The description adds meaningful behavioral detail: it returns IDs only and is token-cheap, pagination follows has_more/next_cursor, and BAD_REQUEST causes are explained with remediation steps. This goes well beyond what the annotations 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?

The description is well-structured with clear sections: purpose, USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, and ERROR. It is front-loaded with a one-sentence purpose statement, and every section earns its place by carrying actionable guidance.

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

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

Even without an output schema, the description provides the return envelope and pagination contract, error handling guidance, and explicit sibling alternatives. Combined with fully documented schema parameters and read-only annotations, an agent has everything it needs to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining which parameter groups matter (notified, tagged, label filters), how next_cursor works for paging, and that ID lists require IDs rather than names with a 50-entry limit. Most parameter-level detail still lives in the schema, but the description supplements it usefully.

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

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

The description opens with a specific verb and resource: 'Find message IDs by notified state, mentions, labels, creator, conversation or workspace — returning IDs plus cursor metadata.' It immediately differentiates the tool from siblings like list_messages and search_messages_by_heard_status, so an agent can understand what this tool uniquely does.

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

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

The USE WHEN and USE INSTEAD sections give explicit routing guidance: use this for filters list_messages cannot express (notified_status, tagged_user_ids, label_ids), and use list_messages when full bodies are needed, or search_messages_by_heard_status for heard state. This leaves little ambiguity about when to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: the return shape, the unheard_counts_by_channel aggregation, and the warning that the full payload is much larger, prompting the NARROW guidance. No contradiction with 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, then uses clear labeled sections (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW). Every section earns its place and the format aids scanning. Length is justified by the tool's complexity, with no redundant sentences.

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

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

For a 7-parameter tool with no output schema, the description covers the key gaps: usage context, alternatives, response shape, and payload optimization. The one limitation (no date filter) is disclosed. It stops short of describing pagination or interaction with limit, but the schema already documents limit's range and default, so the combination is adequate.

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 parameters are already fully documented. The description adds real value by recommending a specific response_fields dot-path allowlist, demonstrating with an example how to shrink the payload. It also reinforces that heardStatus='unheard' is the unread filter. This goes beyond mere schema repetition.

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 ('Find messages by whether you have listened to them') plus a distinct capability not implied by the name: per-conversation unheard counts. It differentiates from siblings by naming search_message_ids and list_messages as alternatives. The purpose is unambiguous and actionable.

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 USE WHEN section explicitly frames the intended scenario ('What have I not listened to yet' / 'catch me up') and flags the unread filter. USE INSTEAD names exact alternatives (search_message_ids for notified state/mentions/date anchors; list_messages for plain history) and discloses a key limitation: no date filter. This is exemplary when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details beyond the schema: name search only matches contacts, the exact return shape, the instruction to use id in other tools, and NOT_FOUND error semantics with recovery guidance. No contradiction with 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 organized with clear labels (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, ERROR) and front-loaded with the primary purpose. Every section serves a distinct purpose: routing, constraints, example, output format, and error handling. No redundant or filler content.

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

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

For a tool with no output schema, the description compensates by specifying the return fields and the NOT_FOUND error behavior. It covers prerequisites, parameter constraints, alternatives, output usage, and error recovery, making the tool fully callable by an agent without further inference. The annotations cover safety, and the description covers the rest.

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?

Although schema coverage is 100%, the description adds crucial semantics: 'Supply exactly one' enforces exclusivity among the three parameters, and the note that name search only matches contacts clarifies the meaning of the name parameter beyond its schema description. The example also demonstrates a valid parameter combination.

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 ('Find a single user by email, phone or name') and differentiates from siblings like search_users (plural) and get_user (by ID). The phrase 'Find a single user' immediately signals scope and distinguishes the tool from alternatives.

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 explicit USE WHEN conditions ('Resolving ONE person', 'Supply exactly one of email, phone or name') and USE INSTEAD alternatives with rationale (search_users for arrays, get_user when ID is known). The contact-only limitation for name search is also clearly stated, giving the agent actionable routing logic.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds genuinely useful behavioral context: 'Name search only matches your contacts' reveals a filtering quirk, and 'If a name returns more than one candidate, ask which person was meant rather than guessing' prescribes handling for ambiguity. The NARROW note about payload size also discloses performance characteristics.

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?

Every labeled section (USE WHEN, USE INSTEAD, EXAMPLE, RETURNS, NARROW) earns its place, and the primary purpose is front-loaded in the first sentence. The labeled format makes scanning easy, and despite the length, there is zero filler or repetition of schema content.

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

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

For a tool with 5 optional params and no output schema, the description covers everything an agent needs: what it returns (array of user objects with optional fields), how to disambiguate results, how to scope names, and how to shrink the payload. Combined with annotations covering the safety profile, no critical operational detail 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 adds value beyond the schema: the EXAMPLE `{"names":["Brett"]}` demonstrates the argument shape, and the NARROW line explains exactly how response_fields should be used ('pass response_fields ["id","full_name"] unless you need more'). This goes beyond the schema's terse 'Dot-path allowlist' wording.

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

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

The opening line, 'Resolve several users at once by emails, phones, IDs or names,' names a specific verb, resource, and scope explicitly. The 'at once' phrasing immediately distinguishes it from the sibling `search_user` (single lookup), so an agent can tell them apart without inspecting 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?

The USE WHEN section states the exact trigger condition ('Turning a list of people into user IDs in one call') and even names the alternative routes: `search_user for single lookup, get_user for a full profile once the ID is known. This is explicit when/when-not guidance with named alternatives — nothing 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 the operation is not read-only and is destructive, so the description's job is lighter. It adds useful context by clarifying that this tool only sets status, not other fields, and by stating the return value. It does not explicitly warn that a previous status is overwritten, but the status enum makes that mostly self-evident.

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 well-structured with labeled sections: move semantics, USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS. Every sentence earns its place, and the most important scoping detail appears before the usage guidance.

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

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

For a two-parameter status setter, this is complete. It covers all parameter semantics, provides a source for the id, gives usage conditions, and explains the return shape by referencing `get_action_item`. No output schema exists, but the description handles that gap sufficiently.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains where `id` comes from with an exact field path, maps each `status` enum value to a real intent ('completing', 'reopening', 'promoting'), and provides a concrete JSON example.

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 leads with a specific verb and resource: 'Move an action item between `suggested`, `todo` and `done`.' It names the exact status transitions and explicitly contrasts itself with `update_action_item`, so an agent can distinguish it from siblings 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 USE WHEN block gives explicit triggering conditions for each status change, and USE INSTEAD tells the agent to prefer `update_action_item` for other fields. The FIRST instruction even explains how to obtain `id` from `list_my_action_items`, making the calling workflow concrete.

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

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

Annotations only include readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It discloses that items are saved with status 'suggested', that the extraction runs inline (no polling), that results come back immediately, and that it may take a few seconds. These are meaningful behavioral traits beyond what annotations imply, and there is no 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?

The description is well-structured with labeled sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS) and front-loads the core purpose. Every section contributes value, but it is slightly verbose (~150 words). It could be trimmed slightly without losing clarity, yet the structure makes it easy to scan.

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

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

With only 2 parameters and no output schema, the description provides all necessary context: return format (array of items with fields), status behavior, alternatives, prerequisites, and expected latency. An agent has everything needed to invoke it correctly and interpret results. Nothing essential is missing.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds value by explaining that message_id comes from list_messages (field results[].id) and provides an example, which goes beyond the schema. However, it does not add much about response_fields beyond what the schema already states; the added context is useful but not extensive.

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

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

The description opens with a specific verb and resource: 'Extract action items from ONE message and return them immediately.' It clearly distinguishes from the sibling suggest_action_items_from_messages by emphasizing 'ONE message' vs. multiple, and mentions the alternative create_action_item for known tasks. The purpose is unambiguous and differentiates among siblings 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?

Explicit 'USE WHEN' and 'USE INSTEAD' sections state exactly when to call this tool (single message, turning into tasks) and when to use alternatives (multiple messages use suggest_action_items_from_messages; known tasks use create_action_item). It also instructs to get message_id from list_messages first if not available. This is comprehensive and leaves no ambiguity.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, but the description goes far beyond: it explicitly states that the tool 'runs in the background', that it returns 'ACKNOWLEDGEMENT ONLY', and that results must be retrieved by polling a listing tool with `status: 'suggested'`. This discloses the asynchronous behavior and the fact that no items are returned directly, which is not inferable from 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?

The description is well-structured with clear sections (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS). It front-loads the critical asynchronous behavior and usage context, and every sentence serves a purpose—no filler. The example is concise and the length is appropriate for the tool's complexity.

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

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

Given that the tool has a single parameter, no output schema, and a background execution model, the description provides all necessary context: how to trigger, what to expect (acknowledgement only), how to retrieve results (polling with status 'suggested'), and how to obtain the input (from `list_messages`). There is no missing information an agent needs to call this tool correctly.

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

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

The schema covers 100% of parameters, with `message_ids` described as 'List of message IDs'. The description adds that message IDs come from `list_messages` (field `results[].id`) and provides an example usage JSON, which goes slightly beyond the schema's basic type info. However, this is mostly supplementary; the schema already documents the parameter adequately, so a 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 clearly states the tool's purpose: 'Queue AI extraction of candidate action items from specific messages.' It specifies the resource ('specific messages'), the action ('extract candidate action items'), and the asynchronous nature ('Runs in the background'). The sibling `suggest_action_items_from_message` (singular) is explicitly contrasted, so an agent can distinguish them immediately.

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 provides explicit usage guidance: 'USE WHEN: Turning a conversation into tasks' and 'USE INSTEAD: 'suggest_action_items_from_message' (singular) for a SINGLE message' and 'create_action_item when you already know the task'. It also instructs to poll `list_my_action_items` or `list_action_items` with status 'suggested' and to get `message_ids` from `list_messages` if needed. This leaves no ambiguity about when to use this tool versus 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 are minimal (readOnlyHint=false, no destructiveHint), so the description carries the burden. It discloses that message selection is automatic, states the return format mirrors `run_ai_action`, and documents the BAD_REQUEST error case. It does not discuss side effects like resource consumption or rate limits, but it adds meaningful behavioral 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?

Structured with clear headers (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS, ERROR) that front-load the most critical information. Each section earns its place, though the text is somewhat lengthy. The structure compensates for verbosity, making it easy to scan.

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

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

Given 8 parameters, no output schema, and moderate complexity, the description covers all essential context: prerequisites, usage conditions, an example, the exact return shape, and an error condition. An agent has everything needed to invoke the tool correctly without additional lookups.

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 covers all parameters, but the description adds significant usage guidance: it explains the `message_ids` omission behavior (uses recent messages, saves a `list_messages` call), tells the agent to get `prompt_id` from `list_ai_actions` and `conversation_id` from `list_conversations`, and provides an example. This clearly exceeds the baseline.

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

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

The description opens with a precise statement of what the tool does: 'Summarize a conversation by running an AI Action over its recent messages.' It clearly names the resource (conversation) and mechanism (AI Action), and explicitly differentiates from the sibling `run_ai_action` by stating when to use one over the other. No ambiguity.

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

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

Provides explicit USE WHEN and USE INSTEAD directives, naming `run_ai_action` as the alternative and the condition that selects it (knowing exact message_ids or wanting a non-summary action). Also includes FIRST prerequisites for obtaining `prompt_id` and `conversation_id` from sibling tools, leaving nothing 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 indicate mutation (readOnlyHint=false, destructiveHint=true). The description adds crucial partial-update semantics (omitted fields are left unchanged), the return shape (same as `get_action_item`), and how to source the id. This goes beyond the annotations and is not contradictory.

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

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

The description is well-structured with clear section labels (USE WHEN, USE INSTEAD, FIRST, EXAMPLE, RETURNS). Each section earns its place, the main purpose is front-loaded, and there is no unnecessary repetition or fluff.

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 five parameters and no output schema, the description covers the purpose, usage context, prerequisites, partial-update behavior, and return format. It also names the sibling to avoid confusion. No critical information is missing 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 coverage is 80% (4 of 5 parameters have descriptions). The description reinforces the key rule that only fields to change need be sent, and the example clarifies the structure. It adds a general principle the schema does not fully articulate, elevating it above the baseline for high coverage.

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

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

The description states a specific verb ('Change'), the resource ('an action item'), and lists the mutable fields (title, notes, assignee, due date). It explicitly distinguishes this from the sibling `set_action_item_status`, making the tool's purpose unambiguous even 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 explicit 'USE WHEN' and 'USE INSTEAD' sections, clearly stating when to use this tool and when to use the alternative for status changes. It also instructs the agent to obtain the `id` from `list_my_action_items` first, a concrete prerequisite that prevents errors.

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 signal that this is a mutating operation with destructiveHint=true. The description adds useful context by stating that only the name changes, that the updated folder is returned in the same shape as `get_folder`, and that `name` is the only editable field. It does not go into irreversibility or permissions, but the annotation plus mutation semantics cover the core behavior.

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

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

The description is tightly organized with labeled sections: purpose, when to use, alternative, prerequisite, example, and return shape. Every sentence adds actionable information without unnecessary filler.

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

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

For a simple two-parameter rename tool, the description covers when to use it, when not to, where to get the ID, a worked example, and the return shape. It is sufficiently complete even without an output schema.

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

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

The schema only documents `name` as 'New Folder Name' and leaves `id` undocumented. The description compensates by explaining that `id` comes from `get_root_folders` and providing a complete JSON example that clarifies both parameter roles.

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 operation 'Rename a folder' and explicitly distinguishes it from `move_folder` and other sibling operations. It also clarifies that `name` is the sole editable field, leaving no ambiguity about the tool's scope.

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

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

Provides explicit USE WHEN and USE INSTEAD guidance, routing agents to `move_folder` for repositioning. It also gives a FIRST directive explaining where `id` comes from and that `get_root_folders` should be called first if needed.

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