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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the draft is generated from the organization's configured prompts and knowledge base, and the result is returned rather than sent, which explains why the call is side-effect-free.

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

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

Two sentences with zero filler; the core purpose is front-loaded and the key differentiator (no send) closes it. Every clause earns its place.

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

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

For a simple two-parameter, no-nested, read-only tool with full schema coverage and annotations, the description is nearly sufficient. It notes a draft is returned but does not describe draft characteristics (e.g. it is not persisted, single suggestion), a minor gap given there is no output schema.

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

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

Schema description coverage is 100% and both parameters carry descriptions (including a pointer to organization_list for the org id), so the schema does the heavy lifting. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Generate an AI reply draft for a conversation') and immediately scopes it relative to the similar-looking conversation_reply sibling by specifying 'without sending it.' An agent can distinguish it from the send path 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 'without sending it' clause implicitly signals the when-to-use case versus conversation_reply, but the description never explicitly names the alternative or states a positive selection condition (e.g. 'use before replying to preview'). Usage is implied rather than spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add behavioral context — and it does: the response is shaped by the organization's persona and response rules, and knowledge-base entries are injected unless disabled. It still omits latency, cost, and whether the answer is grounded/citable, which matters for an AI-backed call.

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

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

Two tight sentences with the core behavior front-loaded, followed by usage and context guidance. The middle clause 'it answers with the organization's persona and response rules and... the knowledge base entries' is slightly run-on but still efficient.

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

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

With no output schema, the description must convey the return nature — and it does, describing a free-form textual answer composed from persona rules plus retrieved knowledge. Remaining gaps (answer length, citation behavior, error modes) are minor for a free-form generation tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including removeKnowledge. The description's 'unless disabled, the knowledge base entries matching the prompt' reinforces that switch but adds little beyond the schema's own wording, matching the baseline of 3 for a fully documented schema.

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

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

States a specific verb and resource: 'Run a free-form prompt through the organization's AI' and clarifies it answers with the org's persona and response rules. This implicitly separates it from siblings like ai_draft_reply and ai_translate, but never names an alternative explicitly, so it stops short of a 5.

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

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

'Use it to draft texts or answer questions from the knowledge base' gives a clear context for when to reach for this tool. It offers no exclusions or named alternatives (e.g. when to prefer ai_draft_reply or knowledge_search instead), so it lacks the explicit when-not guidance that would earn a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the key side-effect boundary ("without creating a conversation") and previewing the three-part return (classification, spam flag, generated reply) for a tool that has no output schema.

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

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

Two tightly written sentences, with the core action and its side-effect constraint front-loaded and the use case following. Every clause earns its place with no redundancy.

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

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

With no output schema, the description compensates by describing the return payload, and it clarifies the non-mutating behavior that annotations only imply. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including a helpful pointer to organization_list for the organizationId. The description adds no further parameter-level meaning, so the baseline 3 for schema-documented params is appropriate.

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

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

The description opens with a specific verb+resource ("Simulate an incoming customer message") and immediately clarifies scope by stating it works "without creating a conversation." It also enumerates exactly what it returns (classification, spam verdict, reply), letting an agent distinguish it from siblings like ai_draft_reply or conversation_reply without opening any schema.

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

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

It gives a clear context for use ("Useful to check classifications, prompts and knowledge"), which tells the agent this is a pre-flight/testing tool rather than a production action. However, it names no alternative tool and states no explicit when-not-to-use condition, so it falls short of the 5-level 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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing the detection-first behavior, the untouched-text + translated=false case, and the failure signal of an empty translation. These are non-obvious behavioral traits an agent needs to interpret results correctly.

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

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

Three short sentences, front-loaded with the core action, then the edge-case behavior. Every sentence carries distinct 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?

With no output schema, the description compensates by explaining the meaningful return signals (translated=false, empty translation = failure). Combined with full schema coverage and annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents text, language (two-letter code), and organizationId. The description adds only a loose restatement of the language parameter and no syntax beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Translate a text into a language') and immediately frames the concrete use case (translating a reply into the customer's language before conversation_reply). This distinguishes it from siblings like ai_draft_reply or conversation_reply without needing the schema.

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

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

Gives clear usage context by naming the workflow it belongs to (before conversation_reply) and explains the pre-check behavior. It stops short of explicit exclusions or naming an alternative tool for when not to translate, but the when-to-use signal is strong.

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

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

Annotations only declare the non-readonly/non-destructive/non-idempotent profile, but the description adds critical traits beyond them: the plaintext key is returned exactly once, must be relayed immediately, is a secret, and cannot be retrieved later. It also discloses the admin-permission requirement.

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

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

Three tight sentences with zero filler; the core operation leads and the one-time-secret caveat follows immediately, which is the highest-value information front-loaded appropriately.

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

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

With no output schema, the description correctly compensates by explaining that the response carries the plaintext key exactly once and cannot be recovered. It does not describe the rest of the returned key object, but for a 3-param create tool it is essentially complete.

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

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

Schema description coverage is 100%, so all three parameters (name, expirationDays, organizationId) are already documented in the schema, including the 'omit or 0 for never expires' semantics. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb+resource+scope: 'Create a new named API key for an organization.' The 'create' verb cleanly distinguishes it from the sibling api_key_list and api_key_delete tools without needing 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 an important prerequisite ('Requires organization admin permission'), but never states when to use this over alternatives (e.g., api_key_list to review existing keys, or when to create vs rotate). Usage is implied by the verb rather than guided.

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

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

Adds substantial context beyond the destructiveHint annotation: integrations stop working immediately, the MCP server itself may be destroyed if the acting key is deleted, and organization admin permission is required. These are exactly the consequences an agent must surface before calling.

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

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

Three compact sentences, front-loaded with the action, followed by the impact and the permission requirement. 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, non-idempotent operation with no output schema, the description covers effect, self-destruct risk, and authorization. An agent has everything needed to warn and act correctly.

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

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

Schema description coverage is 100% – both organizationId and apiKeyId are documented with pointer tools (organization_list, api_key_list). The description adds no parameter detail beyond the schema, so baseline 3.

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

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

States a specific verb+resource ('Delete (revoke) an API key of an organization') and clarifies the effect of deletion. An agent can distinguish this from api_key_create, api_key_list, and webhook_rotate_secret readily.

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

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

Implied usage (revoking a key), with a strong consequence note, but no explicit when-to-use/when-not or named alternative procedures (e.g., rotate vs delete). Presents the precondition (admin permission) but not the decision criteria.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: it never returns key values (a real security-relevant constraint) and it requires admin permission, which affects whether the agent should attempt the call.

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

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

Three tight sentences, each carrying distinct information: what is returned, the security constraint, and the permission requirement. Nothing is redundant and the 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?

With no output schema, the description helpfully enumerates the returned fields (name, masked prefix, created, last used, expiry), so the agent knows the response shape. A single-param read tool is otherwise fully specified; only minor gaps remain.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema fully documents organizationId and even cross-references organization_list. The description adds no parameter-level detail, which is appropriate at this coverage level – baseline 3.

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

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

States a specific verb and resource ('List the named API keys of an organization') and enumerates the returned fields, so the agent knows exactly what is produced. It does not explicitly contrast with the sibling api_key_create/api_key_delete, but the naming makes the read/write split obvious.

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

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

It gives a prerequisite ('Requires organization admin permission') which is useful for deciding feasibility, but offers no explicit when-to-use guidance or named alternatives. Usage is implied rather than instructed.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description adds nothing on top — no note about validation failures, required prior setup, or what happens on duplicate names — despite being free to do so.

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

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

One sentence with zero waste and the action front-loaded, but it is under-specified rather than genuinely concise; there is no content to be efficient about.

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

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

For an 11-parameter creation tool with no output schema, the agent gets almost nothing about the concept of a 'classification', required setup ordering, or failure modes. Annotations cover the safety profile, but the description should do more for a mutation of this surface area.

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% across all 11 parameters, including cross-references (prompt_list, template_list, member_list), so the schema carries the full burden. The description contributes no additional parameter meaning, making the baseline 3 appropriate.

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

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

"Create a classification" merely restates the tool name and title with no additional scope, field, or resource detail. It does not distinguish this from relatives like classification_update, classification_get, or classification_delete beyond what their names already convey.

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

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

There is no when-to-use guidance, no prerequisites (e.g. that organizationId/promptId/templateId must reference existing entities), and no mention of alternatives. The create semantics are inferable from the name alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: affected conversations are reassigned to reassignTo or left unclassified, and knowledge entries may be impacted. It does not state irreversibility or permission requirements, so not a 5.

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

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

Two sentences, zero filler. The destructive action is front-loaded and the consequential behavior and the recommended pre-flight check follow in priority order. Every clause carries operational weight.

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 tool with full annotation coverage, a 100%-documented schema and no output schema, this is close to complete: consequences are spelled out and a discovery tool is recommended. It stops short of stating whether the deletion is reversible or what happens to knowledge entries, deferring that to classification_impact.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning over the schema by disclosing the fallback behavior of the optional reassignTo parameter ('or left unclassified'), which the schema does not state. organizationId and classificationId gain nothing beyond the schema's own pointers.

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 ('Delete a classification'), immediately distinguishing it from classification_create, classification_update, and classification_impact in the sibling set. It goes further by stating the resulting state of affected data, so the agent knows exactly what operation this is.

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

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

It names a concrete pre-flight alternative and the condition that selects it: 'Use classification_impact first to see how many conversations and knowledge entries are affected.' That is clear when-to-use-before-this guidance, though it stops short of stating outright exclusions or when not to delete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that, such as whether the lookup errors on a missing id or requires specific permissions beyond organization scoping.

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

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

A single short sentence with the verb and scoping constraint front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a simple two-parameter read, the description plus rich annotations and full schema coverage is just barely sufficient. However, there is no output schema, and the description does not hint at what a classification object contains or how errors are surfaced, leaving a moderate gap.

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

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

Schema description coverage is 100%, and both parameters (organizationId, classificationId) are documented in the schema with cross-references to organization_list and classification_list. The description's 'by id' adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('one classification') and scopes it to a single item via 'by id', which implicitly separates it from classification_list. It does not, however, explicitly distinguish itself from other singular siblings like classification_impact or classification_statistics.

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

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

There is no guidance on when to use this tool versus classification_list, classification_impact, or classification_statistics. The 'by id' phrasing is the only indirect usage signal, and prerequisites (e.g., needing an existing classification id) are implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the agent knows this is a safe, non-mutating call. The description adds that it is a preview and what scope it covers, but says nothing about result format, counts, or completeness guarantees 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?

A single front-loaded sentence with the verb first and zero filler; nothing could be cut without losing meaning.

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

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

For a small read-only tool with full schema coverage and safety annotations, the description supplies enough for correct invocation. It lacks an explicit statement of what the preview returns, but with no output schema and read-only safe semantics, the gap is minor.

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

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

Schema description coverage is 100% and both parameters are documented there, including cross-references to organization_list and classification_list. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (preview), resource (classification deletion impact) and even enumerates affected entity types (conversations, knowledge entries). It is clearly distinguishable in intent from sibling classification_delete, though it does not name that sibling explicitly.

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

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

'Preview what deleting ... would affect' strongly implies a pre-deletion safety check, but the description never states when to call this versus going straight to classification_delete, nor any prerequisites beyond the schema's pointer to classification_list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that automation settings are bundled into the output, but says nothing about pagination, result size, or permissions. A 3 is appropriate given the annotation coverage.

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

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

A single sentence with zero filler, front-loading the verb and resource and then listing the returned fields. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the fields returned, which compensates well. Minor gaps remain around ordering/pagination of a list operation, but for a one-parameter read tool the definition is close to complete.

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

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

With 100% schema description coverage on the single organizationId parameter (including the pointer to organization_list), the schema already carries the full parameter burden. The description adds no format or constraint detail beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb (list) and resource (classifications) with organizational scope, and enumerates the included automation settings (AI reply, draft, auto close, assignee, prompt, template). It is clearly distinct in intent from classification_get, though it does not name a sibling explicitly.

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

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

There is no guidance on when to use this tool versus classification_get, classification_statistics, or classification_impact. The only routing hint ('Use organization_list to find it') is attached to the parameter, not the tool, so it belongs to the schema, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that profile: it does not state whether closed/spam conversations are counted, whether a time range applies, or how the grouping is structured, which matters for an aggregate tool.

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

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

One sentence with zero filler and the resource/scope front-loaded. It is appropriately sized for the schema complexity, though it is arguably thin for a statistics endpoint that has filtering behavior worth stating.

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

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

With no output schema, the description must at least imply the return shape, and it does (a count per classification). However, it omits whether results respect filters, time windows, or conversation states, leaving the agent unable to predict the exact scope of the counts.

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

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

There is a single required parameter (organizationId) at 100% schema description coverage, and the schema itself already tells the agent to use organization_list to find it. The description adds no parameter meaning, so the baseline of 3 for fully documented parameters applies.

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

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

States a specific resource relationship: conversation counts grouped by classification, scoped to an organization. It conveys the aggregate nature of the tool clearly, but does not distinguish itself from siblings like classification_list, classification_impact, or conversation_stats, so an agent must infer which classification-related aggregate to call.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as conversation_stats, conversation_totals, or classification_list. The agent learns what the tool returns but not when it is the right choice over neighboring statistics tools.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond them: that omitted fields are left untouched (partial update). It says nothing about permissions, failure modes for invalid ids, or side effects on AI auto-reply settings.

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

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

Two short sentences, front-loaded with the action, with no filler. The second sentence partially restates what the schema's two-required-param structure already implies, which keeps it from a 5.

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

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

For a 12-parameter mutation with rich schema descriptions and an annotation set, the description is minimally sufficient but thin. It omits any mention of how the AI-related flags (aiReply, aiReplyDraft, autoClose) interact or what the caller should expect after an update.

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% across all 12 parameters, so the schema already explains name, color, aiReply, promptId, autoClose, templateId, and the rest. The description adds no parameter-level meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Update a classification"), which an agent can distinguish from the create/delete/list siblings by name alone. It does not explicitly contrast with classification_create or classification_delete, so it stops short of full sibling differentiation.

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

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

"Only provide fields to change" is a patch-semantics hint for invocation rather than guidance on when to choose this tool over alternatives. Nothing states prerequisites (e.g. needing an existing classificationId) or when to use create/delete instead.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds the validation rule that at least a name or email is required, which is useful but does not disclose duplicate handling, permission requirements, or other behavioral traits beyond what annotations and schema 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 two short sentences with no wasted words. It is front-loaded with the core action ('Create a contact') and immediately follows with the essential input requirement, making it easy 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?

Given the tool's simplicity, 100% schema description coverage, and clear annotations, the description is nearly complete for basic invocation. It could mention that this is for new contacts only (e.g., not for updating existing contacts), but for a create operation with no output schema, the essential information is present.

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

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

Schema description coverage is 100%, so the parameter-level documentation already explains each field. The description adds a cross-parameter constraint not present in the schema—'Provide at least a name or an email address'—which meaningfully affects invocation since only organizationId is marked required. This extra business rule is valuable beyond the schema.

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

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

The description states a specific verb and resource: 'Create a contact.' It clearly identifies the operation as a creation. However, it does not explicitly distinguish this tool from contact_update or other sibling tools, so it falls short of a 5.

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

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

The description provides no guidance on when to use contact_create versus alternatives such as contact_update or contact_list. The only instruction, 'Provide at least a name or an email address,' is an input constraint rather than usage context, and no exclusions or scenarios are mentioned.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the irreversibility profile is largely covered. The word 'permanently' reinforces that the deletion is unrecoverable but adds little beyond the annotation, and the description says nothing about cascade effects (e.g., whether associated conversations or messages are affected).

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

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

A single front-loaded sentence with no filler or repetition. Its brevity is appropriate, though it is arguably terse for a destructive tool where one more clause about consequences would earn its place.

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

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

For a permanent, non-idempotent delete with no output schema, the description omits any warning about consequences, auth requirements, or side effects on dependent records. An agent has no way to know what else is affected by removing a contact.

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

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

Schema description coverage is 100% and both parameters (contactId, organizationId) are documented in the schema with pointers to contact_list and organization_list. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a contact'), so the action is unambiguous. It does not differentiate from the many sibling *_delete tools (member_delete, conversation_delete, message_delete), though the tool name itself carries that distinction.

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

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

There is no guidance on when to delete a contact versus alternatives such as contact_update or conversation_delete, and no prerequisites or cautions are stated. For an irreversible operation, the absence of any when-to-use context is a real gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds the type-code legend (0=text, 1=link, 2=button), which is genuinely useful return-value context not present anywhere in the schema, but it says nothing about pagination, ordering, or filtering behavior.

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

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

Two sentences with zero filler, front-loaded with purpose, then returning the type legend and downstream usage. Every clause earns its place.

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

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

For a simple read-only list tool, the definition covers purpose, key return fields, the type-code mapping, and the follow-up workflow, while annotations cover safety and the schema covers the single required argument. Nothing an agent needs to invoke it correctly is missing.

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

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

The single organizationId parameter is fully described in the schema (100% coverage), including a pointer to organization_list. The description adds no additional parameter meaning, so the schema-does-the-work baseline of 3 applies.

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

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

States a specific verb (List), resource (custom contact fields), and scope (defined in an organization), and even enumerates the returned attributes (key, name, type). An agent can distinguish this from contact_list, contact_create, and contact_update without opening a schema.

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

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

Explicitly names the downstream consumers: 'Use the keys with contact_create and contact_update.' This tells the agent why it would call the tool and what to do with the result, though there are no exclusions or when-not conditions (which are arguably unnecessary for a discovery endpoint).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description adds genuine value by disclosing what the call returns - custom field values and a conversation count - which is otherwise undisclosed 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?

A single front-loaded sentence with no filler. Every clause earns its place by stating the operation, its scope, and its payload.

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

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

For a simple two-parameter read tool, the description plus rich annotations and a fully documented schema leave little ambiguity. The absence of an output schema is partially compensated by the description naming the returned fields, though it does not cover error cases or empty results.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including how to find them (contact_list, organization_list). The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Get one contact by id') and clarifies scope by saying 'one contact', which implicitly separates it from the list operation. It also names the returned payload (custom field values, conversation count). It stops short of explicitly naming sibling contact_list/contact_update as 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?

There is no explicit when-to-use guidance. The 'by id' phrasing hints that an id is required, but the description never states when to prefer this over contact_list or how the id is obtained. Usage must be inferred entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully adds the scope of returned data (fields and conversation count) but says nothing about pagination or result-size behavior beyond what the schema already documents.

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

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

A single front-loaded sentence with no filler. The purpose and returned data are stated immediately, and every clause earns its place.

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

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

For a read-only list tool with full annotation coverage and 100% parameter documentation and no output schema, the description is largely sufficient. It could still note pagination limits or the difference from contact_get, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100%, so all five parameters (page, limit, search, senderOnly, organizationId) are already documented in the schema, including the pointer to organization_list. The prose only implies searchability, adding little beyond the schema; baseline 3 applies.

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

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

States a specific verb-set (list or search) and resource (contacts/customers) of an organization, and enumerates the returned fields. It is clear on its own, but it never explicitly distinguishes itself from the sibling contact_get, so an agent must infer list-vs-single from the name alone.

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

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

'List or search' implies the read/collection use case, and the search parameter is named in prose. However, there is no explicit when-to-use versus contact_get or when-not guidance, and no mention of prerequisites beyond the schema's own organizationId hint.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-destructive mutation that is not idempotent. The description reinforces the merge semantics with "only provide fields to change", but adds nothing about permissions, error behaviour, or side effects on unmentioned fields (the schema covers the latter).

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

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

Two short imperative sentences, with the core action front-loaded and the usage caveat second. Nothing is wasted, though the description is on the thin side for a nine-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 mutation tool with no output schema, the definition leans entirely on annotations plus a 100%-documented schema. That combination is just enough to call it correctly, but the description itself contributes almost no behavioural or return-value context.

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

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

Schema description coverage is 100%, including helpful cross-references such as contact_field_list and organization_list, so the schema carries the parameter burden. The description's only addition is the partial-update instruction, which is already echoed by the `fields` description ("Fields not listed keep their value"), so baseline 3 is right.

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 (update) and resource (contact), so the agent knows exactly what the tool does. It does not distinguish itself from neighbours like member_update or organization_update, but the contact-scoped name makes the target 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?

"Only provide fields to change" gives the partial-update contract, which is genuine usage guidance for a PATCH-style call. However, it never says when to prefer this over contact_create or contact_delete, nor what happens if a contact id is invalid, so usage is merely implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, covering the basic safety profile. The description adds no behavioral context beyond the annotation, such as whether closure is reversible, what happens to the conversation thread, or any permission 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?

The description is a single concise sentence with no wasted words. It is front-loaded and readable, though it is so brief that it omits potentially useful structural context.

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 mutation with full schema coverage and annotations, the description is minimally adequate. It does not explain the effect of closing a conversation or how it relates to siblings like conversation_delete, leaving a small but meaningful gap.

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

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

Schema description coverage is 100% for both required parameters, and the schema itself explains that organizationId can be found via organization_list. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear verb and resource: 'Close a customer conversation.' It identifies the action and object, but does not distinguish this tool from siblings such as conversation_update, conversation_delete, or conversation_spam, leaving the agent to infer the difference.

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 no guidance on when to use this tool versus alternatives like conversation_delete or conversation_update. It only restates the action, so the agent receives no explicit context, exclusions, or conditions for use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds that deletion is permanent and cascades to all messages, which is meaningful context beyond the annotations, but it does not clarify auth requirements or whether anything is recoverable beyond the word 'permanently'.

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

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

One short sentence with zero filler, front-loading the action and resource. Every word (including 'permanently' and 'all of its messages') 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 two-parameter destructive delete with full schema coverage and no output schema, what an agent needs is essentially the action and irreversibility, both present. It could go further by noting the effect on related records or the absence of undo, but it is largely sufficient.

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

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

Schema description coverage is 100%, so both required parameters are already documented in the schema, including how to obtain organizationId. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

Clear verb+resource ('Delete a conversation') with added scope ('and all of its messages permanently'), which hints at the cascade distinction from message_delete. It does not name any sibling explicitly, so an agent gets no direct routing signal versus conversation_close or conversation_spam.

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

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

No statement of when this should be used instead of alternatives such as conversation_close (soft close) or conversation_spam. Nothing about prerequisites beyond the schema's note on organization_list, and no exclusions or caution guidance for a destructive operation.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds value by enumerating the returned payload (classification with reason/confidence, last message), but says nothing about permissions, error behavior, or rate limits.

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

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

A single front-loaded sentence with the purpose stated first and the field list following. No wasted words.

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

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

With no output schema, the description usefully compensates by listing the fields returned (status, priority, classification, assignment, contact, language, last message). For a simple read-only two-parameter lookup this is nearly complete, lacking only auth/error context.

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

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

Schema description coverage is 100% and both required parameters (organizationId, conversationId) are documented in the schema itself, including the hint to use organization_list. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a clear verb ('Get') plus resource ('customer conversation by id') and enumerates the returned fields, which lets an agent distinguish it from the plural conversation_list. It does not explicitly name a sibling alternative, so it falls short of the top tier.

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 'by id' phrasing implies single-record lookup rather than listing, but there is no explicit when-to-use, when-not-to-use, or named alternative guidance. Usage must be inferred from context.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds real behavior: the result ordering rule and the fact that ordering switches to relevance when a search is present, plus an enumeration of returned fields (subject, status, priority, classification, assignee, contact, language, last message) — valuable since there is no output schema.

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

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

Two tight sentences with zero filler: the listing scope and ordering come first, followed by the filter-combination and result-content facts. Every clause carries information an agent can act on.

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

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

For a 16-parameter read tool with no output schema, the description covers the essentials: scope, ordering, filter combination, and returned fields. It omits page/limit pagination behavior and does not address what an empty result means, but the schema documents those parameters thoroughly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by stating that filters are optional and combinable (AND semantics) and by tying the 'search' parameter to a different ordering mode, which the schema alone does not express. It does not explain pagination interaction or the spam-omission default beyond what the schema says.

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

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

Names a specific verb and resource (list customer conversations) and adds the ordering contract (highest priority / most recent first, relevance when searching) plus the shape of each result. It does not explicitly distinguish itself from siblings such as conversation_stats, conversation_totals, or conversation_get, so an agent must infer 'list vs aggregate vs single' on its own.

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?

'All filters are optional and combine' is useful invocation guidance and the search-triggered relevance ordering is implied context. However, there is no explicit when-to-use / when-not-to-use statement and no pointer to alternatives (conversation_get for one conversation, conversation_stats for counts), leaving the choice to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine value beyond them by enumerating the returned message content: sender, recipients, text, detected language, team-language translation, and draft/internal-note flags. Since there is no output schema, this pre-empts the main behavioral unknown.

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

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

Two tight sentences, zero filler. The core action and ordering are front-loaded, and the return-field enumeration follows logically.

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 helpfully characterizes the payload shape; pagination and filtering semantics live in the 100%-covered schema. Absent pagination-behavior specifics and any sibling routing, it falls just short of fully self-sufficient.

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

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

Schema description coverage is 100% and all five parameters are documented in the schema, including pagination, search, and the organization_list hint. The description adds no additional parameter semantics, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (messages of a conversation) plus an ordering guarantee (newest first). It is clearly distinguishable from message_get by being a collection read, but it does not position itself against close siblings like conversation_thread or conversation_get.

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

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

The description implies usage by naming the required resource scope, but gives no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as conversation_thread or message_get. The agent must infer the routing itself.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeatability are covered. The description adds the aggregation scope (organization-wide, date range) and enumerates the returned metrics, which is useful return-value context given there is no output schema, but it discloses no auth, rate-limit, or default-range behavior.

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

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

A single dense sentence front-loads the scope before the colon and then lists outputs efficiently with no filler. The long enumeration of metrics is justified because no output schema exists, though the phrasing is noun-heavy rather than action-oriented.

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, enumerating the returned metrics is the right move and partially compensates. However, it omits whether dates are optional or defaulted, how metrics are segmented (per member vs. per organization), and how it relates to the several sibling statistics tools an agent could confuse it with.

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

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

Schema description coverage is 100% and all three parameters are documented, including the YYYY-MM-DD format and the pointer to organization_list. The description only loosely ties startDate/endDate together with 'for a date range' and adds no syntax or default behavior 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 names a clear resource (organization support metrics) and scope (date range) and enumerates the specific metrics returned. It never distinguishes itself from the numerous sibling statistics tools (conversation_stats, conversation_stats_by_member, conversation_totals, inbox_statistics), so an agent cannot tell which of the overlapping stats endpoints to pick.

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

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

There is no when-to-use guidance, no statement of when to prefer this over conversation_stats, conversation_stats_by_member, or conversation_totals, and no note about date-range defaults or prerequisites. The reader must infer usage entirely from the metric list.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, and the description is consistent with that. It adds the 'unread' targeting context, which is mild value, but omits what happens when the conversation is already read, whether the change is reversible, and any permission 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?

A single short sentence with the action front-loaded and zero filler. It is appropriately sized, though it does nothing to route the agent among siblings.

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 and annotations covering the safety profile, the essentials are present. Still missing is any statement of the effect on an already-read conversation or the return behavior, which matters given idempotentHint=false.

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

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

Schema coverage is 100% and both parameters carry descriptions, including a pointer to organization_list for organizationId. The description adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

Specific verb+resource combination ('mark ... as read' for a 'conversation') that an agent can act on. It doesn't distinguish itself from siblings like conversation_update or conversation_close, but the operation is unambiguous.

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

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

No when-to-use guidance, no prerequisites (e.g. whether the caller must be a member of the conversation), and no mention of alternatives such as conversation_update. The 'unread' precondition is implied but never explained.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description usefully reinforces this with 'Sending is irreversible' plus a user-approval precondition — real operational context beyond the hints. It does not cover permission/auth requirements or behavior on partial delivery failure.

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

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

Three tight sentences with the primary action first, then the irreversibility warning, then the mode flags. Every clause carries distinct information and nothing is repeated.

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, no-output-schema mutation tool, the description covers the action, the safety precondition, the two alternate modes, and the sibling used to complete the draft workflow. Missing auth/permission expectations and failure/error semantics keep it from a 5.

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 seven parameters, including language/translation and the two flags, are already documented in the schema. The description restates the internal/draft semantics and adds a workflow hint for drafts, but adds no new syntax or constraints, so the baseline 3 applies.

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

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

States a specific verb and resource ('send a reply to the customer in a conversation') and clarifies the delivery channel, plus the two alternative behaviors (internal note, draft) the same call can produce. An agent can distinguish this from conversation_read, message_get, or message_send without opening the schema.

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

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

Gives concrete conditional guidance: set internal=true for a team-only note, draft=true for a reviewable draft, and names message_send as the tool that sends drafts. It also imposes a precondition ('only call it with a text the user has approved'). It stops short of an explicit when-not-to-use rule versus message_send in the general send case.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar for the description is lower. The description usefully discloses the reversibility (spam=false undoes the marking), which is real behavioral context, but says nothing about permissions, side effects on filters/classifications, or return behavior.

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

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

A single tight sentence that front-loads the primary action and appends the undo mode. Nothing is wasted.

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

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

For a three-parameter boolean toggle with fully documented parameters and no output schema, the description is nearly sufficient. Only minor gaps remain, such as what state the conversation ends in or any downstream side effects.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the default-true behavior of spam. The description restates the spam toggle rather than adding new meaning, so the baseline of 3 applies.

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

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

The description names a specific verb ('Mark') and resource ('a conversation') plus the exact state being set ('as spam'), which lets an agent distinguish it from siblings like conversation_close, conversation_read, or conversation_update. It stops short of explicitly naming those siblings as 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?

It clearly covers the two modes of use – mark as spam, or undo by passing spam=false – giving the agent a usable decision rule. No competing sibling is named or excluded, so it falls short of a full when/when-not treatment.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the aggregation granularity (daily, opened vs closed) but says nothing about defaults when the date range is omitted, timezone handling, or the shape/limits of the returned series.

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

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

A single, front-loaded sentence that identifies the metric, the entity, and the temporal scope with zero filler. Nothing is redundant or padded.

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

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

With no output schema, the description should clarify the returned structure and date-range defaults, but it only hints at 'daily counts.' It is adequate for a simple read tool but leaves the agent guessing about default ranges and response format.

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 organizationId (with a pointer to organization_list) and the two YYYY-MM-DD date fields are fully documented in the schema. The description's 'organization for a date range' only restates what the schema already provides, so baseline 3 applies.

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

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

States a specific resource and metric ('daily counts of opened and closed conversations of an organization') with a clear scope ('for a date range'). It is distinguishable from conversation_list/thread, but it does not differentiate itself from close siblings like conversation_totals, conversation_metrics, or conversation_stats_by_member.

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

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

No guidance on when to choose this over the many overlapping conversation-analytics siblings (conversation_totals, conversation_metrics, conversation_stats_by_member). Usage must be inferred purely from the noun phrase 'daily counts'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read profile is fully covered. The description contributes the aggregation semantics (per-member grouping over a date range), but says nothing about return format or pagination, leaving a gap that the annotations do not fill.

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

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

A single well-structured sentence that front-loads the resource and its grouping dimension. No filler, though the brevity leaves little room for the usage and behavioral context that would round it out.

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 statistics tool with three fully documented parameters and complete annotations, the description conveys enough to invoke it correctly. No output schema exists, so return values need not be explained, though the specific metric definition could be sharper.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema (including 'use organization_list to find it' for organizationId). The description's 'date range' and 'per organization member' phrasing aligns with these but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource: conversation statistics per organization member over a date range, plus the clarifying 'who handled how many conversations'. This distinguishes it from ungrouped siblings like conversation_stats and conversation_totals, but it does not explicitly name those 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?

No when-to-use or when-not-to-use guidance is given. With siblings such as conversation_stats, conversation_metrics, and conversation_totals present, the description never states which one an agent should pick for a per-member breakdown versus a global aggregate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful notion of a single consolidated call, but does not mention the markRead flag's side effect of mutating read state nor any return shape. Given annotations carry the safety burden, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the capability and followed by the routing rule. Every sentence earns its place with no 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?

Complete for a read-only retrieval tool whose annotations already convey safety and idempotency, and no output schema exists to require a return-value description. The only minor gap is the unmentioned markRead side effect, but otherwise nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so organizationId, conversationId, and markRead are all documented in the schema itself. The description adds no parameter-level meaning beyond implying a full-history fetch, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (a conversation together with all of its messages), and explicitly contrasts with the sibling combination conversation_get + conversation_messages. An agent can distinguish this from its siblings without opening a schema.

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

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

Names the two alternatives (conversation_get + conversation_messages) and the exact condition that selects this tool ('when the full history is needed'). Clear when-to-use guidance with explicit alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the word 'current', implying live/fresh data, but says nothing about aggregation window, rate limits, or what happens for an org with no conversations.

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

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

A single efficiently front-loaded sentence that wastes no words, and the parenthetical example is the most informative part. It is slightly too terse to be exemplary, but nothing is padded.

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

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

With no output schema, the description bears some responsibility for signalling return values, and it does so only partially via the 'e.g. open and unread counts' example rather than enumerating the actual fields returned. Combined with no differentiation from overlapping sibling statistics tools, it is adequate but incomplete.

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

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

There is a single parameter with 100% schema description coverage, and the schema already explains both the meaning and how to obtain the ID via organization_list. The description adds no further parameter context, so the baseline of 3 applies.

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

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

States a specific resource (conversation totals) and a clear scope (of an organization), with a concrete example of what the totals contain (open and unread counts). It does not, however, distinguish itself from near-identical siblings like conversation_stats, conversation_metrics, or inbox_statistics, which is the remaining gap.

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

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

The description gives no indication of when to call this tool versus conversation_stats, conversation_stats_by_member, or conversation_metrics. Only the schema's parameter note ('Use organization_list to find it') provides any routing guidance, and only for obtaining the ID, not for 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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds partial-update behavior ('only provide fields to change'), but says nothing about permissions, whether reassignment triggers notifications, or side effects of changing a conversation's contact.

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

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

Two tight sentences with the resource and mutability front-loaded, and no wasted language. The field list is long but each item maps to a real parameter, so it 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 10-parameter mutation tool with no output schema, the description is adequate on what can change but silent on side effects, permission requirements, and how it relates to the overlapping specialized siblings. Annotations cover the safety profile, but the overlap with conversation_close/read/spam leaves genuine ambiguity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names the updatable fields but adds no syntax, format, or constraint detail beyond what the schema already provides (e.g., status codes, two-letter language code).

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

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

Clear verb+resource ('Update a customer conversation') with an explicit enumeration of the mutable fields, so an agent knows exactly what this tool mutates. It does not, however, distinguish itself from siblings that achieve overlapping outcomes (conversation_close, conversation_read, conversation_spam), which handle status/spam changes as dedicated tools.

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

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

'Only provide fields to change' conveys partial-update semantics, which is useful, but there is no guidance on when to use this tool versus the specialized siblings conversation_close, conversation_read, or conversation_spam. No prerequisites or exclusions are stated.

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

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

Annotations already disclose non-read-only, non-idempotent, non-destructive behavior, so the safety profile is covered. The description adds the useful fact that filter criteria are optional and AND-combined, but says nothing about duplicate-name handling, permissions, or what is returned on success.

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

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

Two short sentences with the core purpose front-loaded and the parenthetical clarification placed immediately after. No filler, nothing redundant.

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

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

For a 14-parameter mutation with no output schema, the description is thin: it omits duplicate-name semantics, error conditions, and confirmation/return behavior. The thorough input schema compensates for parameter documentation, so the definition is adequate but not complete.

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

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

Schema description coverage is 100% and the schema itself documents rich search syntax and date formats, so the baseline is 3. The description only adds the optionality/AND-combination rule, which is marginal value on top of the schema.

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

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

States a specific verb and resource ('Save a conversation filter') and clarifies with the appositive 'a named view in the inbox,' which tells an agent what a filter actually is. It distinguishes itself adequately from filter_get/filter_list, though it never explicitly contrasts with the sibling filter_update, which is the nearest 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 only guidance offered is about parameter behavior ('All criteria are optional and combine'), not about when to choose this tool. There is no statement of when to use filter_create vs. filter_update (e.g., whether it fails or overwrites when a filter with the same name exists), so the agent must infer routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is a destructive, non-idempotent write. The description adds no behavioral context beyond restating the action—it doesn't explain permanence, required permissions, or side effects.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the action and resource immediately, which is optimal for a simple delete 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 simple delete operation with complete annotations, a full schema, and no output schema, the description is largely sufficient. It could mention irreversibility or required permissions, but the destructive annotation and schema already cover the critical call details.

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

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

Schema description coverage is 100%, with both parameters (filterId and organizationId) fully documented and cross-referenced to helper tools. The description adds no parameter detail, which is acceptable given the schema covers everything, so baseline 3 applies.

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

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

The description states a specific verb ('Delete') and resource ('a saved conversation filter'), making the tool's action clear. It does not explicitly differentiate itself from sibling tools like filter_list or filter_update, but the verb and resource combination is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related tools. The schema gives hints (e.g., 'see filter_list') but the description itself provides no usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the filter is 'saved,' which is minor context, and says nothing about error behavior for missing ids or the response shape.

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

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

A single front-loaded sentence with zero wasted words; the resource and lookup key are stated immediately.

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

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

For a simple read-only getter whose annotations and schema (100% coverage) cover the essentials, the description is nearly complete. Only minor gaps remain around failure behavior, and no output schema exists that would need explaining.

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

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

Schema description coverage is 100% and both parameters are documented with helpful cross-references (filter_list, organization_list). The description's 'by id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('saved conversation filter') with scope ('one ... by id'), which distinguishes it from filter_list and filter_create. It does not name the sibling tools explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as filter_list for finding an id. The 'by id' phrasing only weakly implies the tool is for retrieving a known filter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description contributes only that results are scoped to the authenticated user and include criteria plus conversation counts; it says nothing about pagination, ordering, or empty-result behavior. With annotations carrying the behavioral load, this modest addition warrants a 3.

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

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

A single front-loaded sentence that opens with the verb and resource, then qualifies scope and return content. No filler or redundancy, though the trailing clause is the only part adding information beyond the schema.

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

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

For a read-only, single-parameter list tool with full schema coverage and annotations covering safety, the definition is nearly sufficient. Since there is no output schema, the mention of criteria and conversation counts usefully signals the return shape. Missing only pagination/ordering details, a minor gap.

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

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

There is a single required parameter and schema description coverage is 100%; the schema already explains organizationId and even points the agent to organization_list. The description only echoes the organization scoping, adding no syntax, format, or default beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb ("List"), a precise resource ("saved conversation filters"), and a scope ("of the authenticated user in an organization"), which cleanly separates it from filter_get/filter_create/filter_update. It also hints at return content (criteria and conversation counts), so an agent can distinguish it from the singular filter_get without opening either schema. It does not explicitly name a sibling, which keeps it just short of a 5.

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

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

Usage is implied by the verb and scope: use this when you need to enumerate a user's saved conversation filters within an organization. There is no explicit when-to-use statement, no exclusion such as "use filter_get for a single filter by id," and no stated prerequisite beyond the org id. Adequate but leaves routing to inference.

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

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

Annotations cover the safety profile (not read-only, not idempotent, not destructive). The description adds genuinely useful behavior beyond them: merge/PATCH semantics where omitted criteria are preserved. However, it says nothing about permission requirements, behavior on an unknown filterId, or what a successful response contains, so the added context is thin.

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

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

Two sentences, no filler, and the core action is front-loaded before the update-semantics caveat. 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 15-parameter mutation with no output schema and no annotations beyond safety hints, the description covers the essential calling convention but omits failure modes, permission prerequisites, and confirmation of what changes. Adequate, not complete.

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

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

Schema description coverage is 100% across all 15 parameters, so the schema already carries the field-level detail (search operators, date formats, ids). The description's only parameter-relevant contribution is the partial-update rule, which is the baseline expectation when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Update a saved conversation filter"), which cleanly separates it from filter_get, filter_create, and filter_delete siblings. It does not explicitly name those siblings, but the operation is unambiguous.

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

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

The second sentence implies the intended usage pattern (partial update), but there is no explicit when-to-use, when-not-to-use, or routing to an alternative. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds value by enumerating the returned fields in the absence of an output schema, but says nothing about behavior on a missing/invalid id.

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

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

A single dense sentence with the resource and id constraint front-loaded and zero filler. The trailing field list is informative rather than wasteful, though it is the only thing keeping this from being maximally tight.

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

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

For a simple two-parameter read tool with full annotation coverage, the description is nearly sufficient: it names the return fields, which matters since no output schema exists. Only the absence of any error/not-found behavior or sibling routing keeps it short of complete.

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

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

Schema description coverage is 100% and both parameters are required and self-documented, so the baseline is 3. The description adds no syntax, format, or lookup detail 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?

States a specific verb and resource ('Get one inbox by id') and enumerates the fields surfaced (type, name, connected account, signature, health, activation state). It clearly reads as a singular-fetch counterpart to inbox_list, though it never names that sibling explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives like inbox_list or inbox_statistics. The only hint ('see inbox_list') lives in the schema, not the description, so an agent gets no selection help here.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the channel coverage and the fields returned, but says nothing about pagination, result limits, or permission requirements for the organization.

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

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

A single front-loaded sentence with no preamble. The channel enumeration is somewhat long but it is the substantive scope information, so it earns its space.

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

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

For a one-parameter, read-only list tool with no output schema, the description covers resource, scope and returned fields. Only the absence of pagination/limits handling keeps it short of complete.

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

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

Schema description coverage is 100%, and the schema itself already tells the agent to use organization_list to find the id. The description adds no meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List the support inboxes of an organization') and enumerates the channel scope plus returned attributes (type, name, health), so an agent can distinguish it from inbox_get and inbox_statistics without opening any schema.

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

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

The description gives no when-to-use or when-not-to-use guidance and never names an alternative such as inbox_get for a single inbox or inbox_statistics for metrics. Usage is only implied by the word 'List'.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false. The description adds useful context about the on-demand fetch/ingestion trigger, but does not explain side effects, whether the call blocks until retrieval completes, or why it is non-idempotent (e.g., repeated calls triggering duplicate retrieval). A mild tension exists between the read-sounding verb 'fetch' and the non-read-only annotation, but the trigger semantics justify it rather than contradict 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?

A single front-loaded sentence with no filler; the action and its trigger contrast are both stated in minimal space.

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

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

For a two-parameter, non-read-only trigger operation with annotations but no output schema, the definition covers what the tool does but omits return behavior (e.g., whether fetched messages or a count is returned) and any completion/blocking semantics that would matter for a non-idempotent refresh.

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%: inboxId and organizationId are both documented with names, lookups (inbox_list, organization_list), and required constraints. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch new messages from an inbox') plus the immediately distinguishing trigger ('now instead of waiting for the next scheduled retrieval'). It is distinguishable from inbox_list/inbox_get by the on-demand trigger framing, though it does not name any sibling explicitly.

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

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

The phrase 'instead of waiting for the next scheduled retrieval' gives a clear context for using it rather than relying on the default schedule. However, it stops short of naming alternatives (e.g., inbox_list to read without triggering) or stating when not to call it, leaving usage implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the observation that the statistics are conversation volumes, and says nothing about time window, granularity, or whether results are paginated.

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

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

One short sentence with the resource front-loaded and no wasted words. It is efficient for a single-parameter read tool, though the parenthetical placement makes the scope slightly awkward.

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 full annotation coverage, a 100%-covered required parameter, and no output schema, an agent can call this correctly. However, the description never indicates what the statistics measure over (time range, breakdown dimensions), leaving the expected result shape entirely unstated in a suite full of overlapping analytics tools.

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

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

Schema description coverage is 100% and the single parameter is documented in the schema itself, including a pointer to organization_list. The phrase 'of an organization' restates what the schema already conveys, so nothing materially new is added.

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

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

States a specific resource (statistics per inbox) and scopes it to an organization, with a clarifying parenthetical that the statistics concern conversation volumes. That is much more informative than a tautology, though it never distinguishes itself from sibling analytics tools like conversation_stats, conversation_totals, or conversation_metrics.

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

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

There is no when-to-use guidance at all. In a suite containing conversation_stats, conversation_stats_by_member, conversation_metrics, and conversation_totals, the agent is given no cue for when per-inbox aggregation is the right pick over those 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds that this reaches an external platform (openWorld) and reports a result, but says nothing about failure/timeout behavior or what the reported result contains.

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

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

A single front-loaded sentence with the action and scope stated immediately. 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 diagnostic tool with no output schema, the description covers what it does but not what a pass/fail result looks like or common failure causes, which is the main thing an agent would want when interpreting the 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?

Schema description coverage is 100%, with inboxId pointing to inbox_list and organizationId pointing to organization_list, so the schema fully documents both parameters. The description adds no parameter meaning beyond that; baseline 3 applies.

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

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

States a specific verb ('test') and resource (an inbox's connection to its platform), plus the platform types involved. It is clearly distinguishable from siblings like inbox_get or inbox_refresh, though it never names them explicitly.

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

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

Usage is implied by the verb — you call this to verify connectivity — but there is no explicit when-to-use guidance or comparison to adjacent tools such as inbox_refresh or webhook_test.

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 idempotentHint=false, so the agent knows this is a non-idempotent mutation. The description adds the purpose context (entries feed AI replies) but says nothing about permissions, duplicate handling, or how created entries affect the knowledge base, so extra behavioral value is modest.

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

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

A single front-loaded sentence with no filler: verb, resource, and the prompt/answer mapping are all packed in efficiently. Only slight loss for borrowing a colon-list to convey parameter meaning rather than stating the effect more directly.

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 5-parameter create tool with no output schema and no nested objects, the description covers the core purpose but omits the notable 'positive: false marks a negative example' behavior, which is the one non-obvious aspect an agent should know before calling it.

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

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

Schema description coverage is 100%, so prompt/completion/organizationId/classificationId are already documented, which sets the baseline at 3. The phrase 'a question or topic and its answer' loosely glosses prompt/completion but adds no syntax or format detail beyond the schema, and the 'positive' negative-example flag goes entirely unmentioned.

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 ('Add') and resource ('knowledge entry') and clarifies its effect ('the AI can use for replies'), then maps the entry to 'a question or topic and its answer'. This is clear enough to distinguish from knowledge_update/delete/search, but it never names a sibling explicitly to reinforce the boundary.

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

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

It says what the tool is for but gives no when-to-use conditions, no prerequisites, and no comparison to alternatives like knowledge_update or the knowledge_source_* tools. The only routing help (organization_list for the id) lives in the schema, not the description.

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

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

The annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds the word 'permanently', which reinforces that this is an irreversible destructive action rather than a soft delete, but it discloses nothing beyond that about side effects or authorization 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?

A single short sentence, front-loaded with the verb and carrying the important 'permanently' qualifier. It is efficient, though it is terse to the point of omitting any additional context that could have been included cheaply.

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

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

With no output schema and complete parameter documentation, the main remaining obligation is behavioral: whether deletion cascades to related knowledge sources, whether the operation can be undone, and whether elevated permissions are required. The description covers only permanence, leaving these gaps for a destructive mutation tool.

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

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

Schema description coverage is 100% for both required parameters, and the schema already explains that organizationId can be found via organization_list. The description adds no additional meaning about parameter format, sourcing of the knowledgeId, or validation constraints, so the baseline 3 applies.

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

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

The description states a specific verb (delete) and resource (knowledge entry) with the crucial qualifier 'permanently', so an agent can distinguish it from knowledge_get, knowledge_update, and knowledge_search. However, it does not name or contrast any sibling tool explicitly, leaving that inference to the agent.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., that the entry id must come from knowledge_search or knowledge_get), and no note that the operation cannot be undone. The agent receives only the bare action.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that – no note on behavior for a missing/unknown id, permissions, or response shape – so it contributes no extra behavioral context.

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

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

A single front-loaded sentence with no filler and no redundancy. It is efficient, though arguably so terse that it forgoes cheap opportunities to clarify usage.

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

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

For a simple two-parameter read whose annotations carry the safety profile and whose schema documents every field, the description is minimally sufficient. There is no output schema, so the agent learns nothing about what a successful fetch returns, which leaves a gap.

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

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

Schema description coverage is 100%, and the schema itself explains both knowledgeId and organizationId (including pointing to organization_list). The description's 'by id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('knowledge entry') scoped by id, so an agent knows exactly what the tool returns. It does not, however, distinguish itself from siblings like knowledge_search or knowledge_source_get, leaving the reader to infer the boundary.

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

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

The description gives no when-to-use guidance and never mentions alternatives such as knowledge_search (for lookup by content) versus this id-based fetch. The only implicit signal is that it requires an id.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: full-text semantics (AND-ed terms, prefix matching, quoted phrases, -word exclusion), that entries are prompt/completion pairs, and that synced articles are chunked under a shared source. It stops short of describing ordering or result shape limits.

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

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

Three dense sentences, front-loaded with the verb and resource, then syntax, then the data model. Every clause carries information the agent needs; nothing is redundant with the name or title.

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

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

With no output schema, the description usefully explains what an entry is (Q/A pair, chunked source), and the search syntax is spelled out. Pagination and ordering semantics are left to the schema, which documents page/limit adequately, 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 coverage is 100%, so baseline is 3. The description goes further by actually defining the query syntax behind the `search` parameter ('words are AND-ed and prefix matched, "quoted phrases", -word to exclude'), which the schema's bare 'Search text.' does not. The other five parameters derive their meaning from the schema.

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

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

States a specific verb and resource ('Search the knowledge base of an organization') and immediately qualifies the scope with the search syntax and entry model. It never names the generic sibling `search` or `knowledge_get`, so an agent cannot fully rule out alternatives from the description alone.

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

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

'Omit search to browse all entries' gives one clear usage mode (browse vs. query). However, there is no guidance on when to prefer this over `knowledge_get` or the generic `search`, and no exclusions are stated, leaving alternative selection 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: it does not state behavior for a missing sourceId, error semantics, or any scope behavior (e.g., that the organization context matters).

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

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

A single short sentence with zero filler and the key noun up front. It is efficient, though terse enough that it carries no supporting structure.

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

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

For a simple read-by-id tool with full annotations and complete schema coverage, this is minimally adequate. It never acknowledges the required organizationId scoping or what happens on a not-found id, and there is no output schema to compensate.

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

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

Schema description coverage is 100%, so both sourceId and organizationId are already documented, including cross-references to knowledge_source_list and organization_list. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('knowledge source'), and the word 'one' signals single-item retrieval versus a list. It does not explicitly distinguish itself from siblings like knowledge_source_list, knowledge_source_sync, or knowledge_source_status, so sibling routing is left to inference.

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

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

The description offers no when-to-use guidance, no prerequisites, and no mention of alternatives. The only routing hint (the pointer to knowledge_source_list) lives in the schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value by disclosing the response contents (sync state, last sync time, last error, synced entry count), which is meaningful 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?

A single well-formed sentence that front-loads the action and resource, then lists the returned data. 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?

For a simple read-only list tool with no output schema, the description conveys enough about what comes back. It could still note pagination or whether all sources are always returned, but that is a minor gap.

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

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

With a single parameter at 100% schema coverage, the schema fully documents organizationId and even points to organization_list. The description adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

Specific verb (List) plus resource (knowledge sources of an organization), and it enumerates source types and the fields returned. It naturally distinguishes itself from the singular knowledge_source_get, though it doesn't name that sibling explicitly.

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

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

Usage is implied by the org-scoped listing, but there is no explicit guidance on when to use this versus knowledge_source_get or knowledge_source_status, nor any prerequisite or exclusion statements. Adequate but leaves routing to inference.

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

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

Annotations already establish this as a safe, idempotent, read-only call, so the safety burden is covered. The description adds useful behavioral context by disclosing that the state enum includes an ERROR state and that a last error field is returned, but it does not say whether this polls or reflects a live sync state. Adequate, with room for more.

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

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

One compact sentence that front-loads the subject and the state values. Every element earns its place, 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 carries the return-value burden and does so by naming four of the key result fields. It stops short of describing pagination, freshness, or the exact response shape, but for a simple status lookup this is close to complete.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema with pointers to knowledge_source_list and organization_list. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific resource (knowledge source) and the informational scope (sync status), and enumerates the concrete fields returned (state, last sync time, last error, entry count). It does not, however, distinguish itself from close siblings like knowledge_source_get or knowledge_source_sync, which an agent may confuse with a status lookup.

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

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

There is no explicit guidance on when to call this versus knowledge_source_get (full details) or knowledge_source_sync (trigger a sync). The usage context is left entirely to inference from the description's phrasing.

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 establish a non-read-only, non-idempotent, non-destructive operation, and the description adds genuinely new context: the work is asynchronous and results must be retrieved separately. It stops short of noting that concurrent invocation may spawn overlapping syncs or what permissions are needed, which would matter given idempotentHint=false.

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

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

Two short sentences with zero filler. The action is front-loaded and the follow-up instruction is second, in the order an agent needs them.

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

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

With no output schema and an async operation, the description correctly covers the critical gap by explaining that execution is background and results come from knowledge_source_status. Missing details such as whether a sync already in progress is rejected or whether permission scopes are required keep it from being fully complete.

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

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

Schema description coverage is 100%; both organizationId and sourceId are documented in the schema, including cross-references to organization_list and knowledge_source_list. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb ('start a sync') and resource ('a knowledge source') and is clearly distinct from sibling tools like knowledge_source_status, knowledge_source_get, and knowledge_source_list. An agent can tell immediately that this triggers an asynchronous job rather than reading state.

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?

Tells the agent what to do after invoking it ('check knowledge_source_status for the result'), which gives clear follow-up context. It does not, however, say when not to call it — e.g., that repeated calls are not idempotent and may start duplicate syncs — so the routing guidance is good but incomplete.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds the partial-update contract, which is useful behavioral context — it tells the agent unspecified fields are left alone. It omits auth/permission requirements and whether changes are reversible.

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

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

Two sentences, zero filler, with the partial-update constraint front-loaded immediately after the action. Every word earns its place.

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

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

For a mutation tool with full schema coverage, complete annotations, and no output schema, the description covers the essentials (what it does, how to call it) but says nothing about permissions, side effects on unspecified fields, or response shape.

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

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

Schema description coverage is 100%, and each parameter (prompt, positive, completion, knowledgeId, organizationId, classificationId) is documented in the schema itself, including a pointer to organization_list. The description adds no parameter-level detail beyond the schema baseline.

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

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

States a specific verb+resource ('Update a knowledge entry'), which cleanly separates it from knowledge_create, knowledge_delete, and knowledge_get. It does not, however, explicitly name those siblings or contrast its scope with them, so it falls short of a 5.

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

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

'Only provide fields to change' implies partial-update semantics, which is genuine usage guidance for how to call it. But there is no statement of when to choose this over knowledge_create or classification_update, and no prerequisites or exclusions.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely new context — the admin permission requirement — which is not in the annotations or schema. It stops short of disclosing duplicate-email behavior or whether an invitation is dispatched.

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

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

Two short sentences, purpose first, prerequisite second, with zero filler. Nothing could be removed without losing 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?

There is no output schema, so the description would ideally hint at what a successful creation returns, and duplicate-email/idempotency behavior is unaddressed. Given the annotations cover safety and the schema covers all inputs, it is adequate but leaves the outcome side thin.

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