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

No annotations are present, so the description carries the full burden. However, the description does not disclose whether this tool has side effects (e.g., creates a record), is idempotent, or requires specific authentication. The behavioral traits are completely opaque.

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

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

The description is extremely short (three lines) but fails to convey essential information. It is under-specified rather than concise; every line is present but not meaningful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, no annotations, and a minimal description, the tool definition is incomplete. An agent cannot determine what the tool returns, whether it is safe to invoke, or how to interpret 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?

The input schema describes both parameters with brief descriptions ('(body) AI prompt identifier', '(body) Content for AI completion'), achieving 100% coverage. The tool description adds no additional context, but the schema itself is sufficient for understanding parameter purpose. Baseline 3 is appropriate.

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

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

The description repeats the tool name ('A I Completion') and includes the HTTP method and path, but does not state what the tool actually does (e.g., 'Generate an AI completion using a prompt'). It is vague and fails to distinguish from other tools like 'send_message' or 'get_ai_prompts'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 is provided on when to use this tool vs alternatives, such as 'get_ai_prompts' or 'send_message'. There is no mention of prerequisites like having a valid prompt_key or how the content is used.

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

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

With no annotations at all, the description carries the full burden and does so: it discloses the usage-count side effect, the at-most-one-action-per-type limit, the 403 refusal path for two action types, the 200/207/500 partial-success semantics, and warns that the success body is `{"message": ...}` rather than the usual envelope. That is substantially more than the schema reveals.

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

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

Front-loaded with the core action, then constraints, then response codes, then the endpoint. Dense but every sentence carries information; the repeated title line and trailing endpoint/tags are mildly redundant but not wasteful.

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

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

For an unannotated mutation tool with no output schema, the definition covers side effects, permissions, partial-failure semantics, and the non-standard response body — everything an agent needs to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it stresses the body is an array of actions rather than an object, reiterates the one-action-per-type constraint, and explains that the action values are coerced to strings for numeric IDs — useful for avoiding type errors. It is largely reinforcing schema content rather than adding new parameter detail.

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

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

States a specific verb and resource ('applies a list of macro actions to a conversation') plus the side effect of incrementing the macro's usage count, and names the concrete endpoint. An agent can distinguish this from read-only siblings like get_macro without opening the schema.

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

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

The description supplies real invocation constraints — allowed action types, refusal of send_reply/send_private_note with 403, and per-action permission requirements — but never says when to reach for this tool versus the macro read tool or other conversation-mutation tools. Usage is implied by the constraints 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?

With no annotations, the description carries the full burden, and it does disclose the required permission scope and the mutation endpoint, which is genuinely useful. It does not state whether the operation is idempotent, what side effects blocking has on the contact (e.g., messaging/consent), or whether the change is 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?

It is short and front-loaded: purpose first, then permission, then endpoint. The trailing 'Tags: Contacts' line is API-doc filler that adds no decision value, keeping 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 simple two-parameter toggle with fully documented schema and no output schema, the description covers purpose, auth scope, and endpoint. It is still missing the behavioral consequences of blocking, which matter for an agent deciding to invoke a state-changing contact operation.

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

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

Schema coverage is 100% and the schema already explains that `enabled=false` blocks and `true` unblocks, so the description adds nothing beyond it. The path template in the description loosely maps `id` to a path parameter, but the schema already labels it as such, making this a baseline case.

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

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

The description names a specific verb pair and resource ('Block or Unblock Contact') plus the concrete endpoint PUT /api/v1/contacts/{id}/block, so an agent knows exactly what the tool does. It is clearly distinct from siblings like delete_contact or update_contact by virtue of the 'block' verb, though it never explicitly contrasts with them.

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

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

Usage is only implied by the verb and the stated prerequisite ('Requires the `contacts:block` permission'). There is no guidance on when to choose this over delete_contact/update_contact, nor any warning about when blocking is inappropriate.

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

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

With no annotations at all, the description has to cover behavior itself. It does disclose one valuable fact beyond the schema: the tool requires the `users:manage` permission. But it says nothing about side effects (welcome email, notifications), what happens on duplicate email, whether the creation is reversible, or what the response contains — a significant gap for a creation tool on a user-account resource.

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

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

It is very short and front-loads the verb and permission, with no filler prose. The 'POST /api/v1/agents' and 'Tags: Agents' lines are near-redundant with the name but efficient and harmless.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description is far too thin: it doesn't explain what is returned, how errors are surfaced, or how the create-only parameters interact. The permission note helps but leaves the agent guessing about most of the tool's contract.

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

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

Schema description coverage is 100%, so the schema already explains all 9 fields, including which are update-only. The description adds no parameter-level meaning, which is acceptable at this coverage level but is not worth more than baseline.

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

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

The title line 'Create Agent' gives a specific verb plus resource, and the POST /api/v1/agents line confirms a creation endpoint. It doesn't explicitly contrast with siblings like update_agent or delete_agent, but the verb makes the distinction self-evident in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 beyond a permission, and no alternatives — it never says to use update_agent when the agent already exists or what to do on duplicate email. The agent has to infer the conditions for calling this from the name alone.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the permission gate, that the rule is ENABLED immediately on creation and will fire on the next matching conversation, and — critically — that the server performs no validation of `rules`, so a malformed rule is stored and silently never matches. It stops short of describing the response payload or any rate limits, but the dangerous behaviors are surfaced.

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

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

Front-loaded with purpose then escalating to permissions, side effects, and a caveat, which is the right order for an agent. The single long inline JSON example is dense but earns its space given the nesting of `rules`; the trailing 'POST /api/v1/automations/rules' and 'Tags:' lines are framing noise rather than agent-relevant content.

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

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

For a six-parameter mutation tool with a deeply nested rules object, no output schema, and no annotations, the description covers the permission requirement, the default-enabled side effect, the silent-failure validation gap, a recovery path, and a concrete example. Nothing an agent needs in order to call this correctly and safely is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description exceeds it by supplying a complete worked example of the deeply nested `rules` structure (group_operator, groups, field_type, operator, actions), which is far more usable than the schema's field-level prose. It also clarifies the create-time behavior of `enabled` implicitly through the 'always enabled' statement.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Creates an automation rule') in the first line, and names the sibling that handles the opposite concern ('use `toggle_automation_rule` to disable it'). An agent can distinguish this from update_automation_rule or get_automation_rule without opening any schema.

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

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

Gives clear preconditions (`automations:manage` permission), says when to route elsewhere for disabling, and prescribes a follow-up read via `get_automation_rule`. It does not explicitly say when to prefer update_automation_rule over creating a new rule, which is the one obvious omission.

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

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

With no annotations present, the description carries the full burden; it does add the meaningful auth requirement (`contacts:write` permission), which is genuine behavioral context. It omits what happens on duplicate email/phone conflicts, whether the call is idempotent, and what the response contains beyond the raw endpoint path.

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

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

The body is short and the key constraint plus permission are front-loaded after a one-line purpose. The repeated header ('Create Contact' then 'Creates a contact') and the 'Tags: Contacts' / raw endpoint lines add minor noise without much selection value.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers the essential permission gate and required-field rule but leaves the agent guessing about the return payload (e.g., created contact ID) and conflict/error behavior.

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

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

Schema coverage is 100%, so each of the six fields is already documented, including the email/phone cross-requirement. The description's restatement of that constraint adds emphasis but no new parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ('Creates a contact') and names the endpoint, so the operation is unambiguous. It does not, however, distinguish itself from siblings like update_contact or create_contact_note beyond the obvious verb 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 precondition that either `email` or `phone_number` must be supplied is useful selection criteria, but there is no explicit when-to-use versus when-not-to-use guidance or named alternative (e.g., update_contact for existing records). Usage is only implied by the verb 'create'.

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

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

With no annotations, the description carries the full burden, and it does supply the required `contact_notes:write` permission and the HTTP endpoint, which are genuinely useful behavioral facts. However, it says nothing about what the call returns, whether duplicate notes are permitted, how the note is attributed, or failure modes for a missing contact 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?

Four short lines, front-loaded with the action, followed by the permission and endpoint. The only mild redundancy is restating the tool name as the first line, but nothing here 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?

This is a simple two-parameter create tool with fully documented parameters and no output schema, so the description covers the essentials (action, auth, endpoint). It stops short of explaining the response or edge cases, which would be needed to reach a 4 or 5 for a mutation tool with zero annotation coverage.

Complex tools with many parameters or behaviors need more documentation. 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 `id` (path parameter) and `note` (body content) documented in the schema itself. The description adds no syntax, format, or length information beyond the schema, so the baseline 3 applies.

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

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

The description gives a clear verb+resource ('Create Contact Note') and reinforces it with the concrete endpoint POST /api/v1/contacts/{id}/notes, so the agent knows exactly what is created and under which parent resource. It does not explicitly differentiate from siblings such as create_contact or get_contact_notes, leaving that inference to the model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 beyond the permission string, and no mention of alternatives such as get_contact_notes or delete_contact_note. The agent must infer that this is the write counterpart to those read/delete 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?

With no annotations at all, the description carries the full burden, and what it contributes is useful but thin: the required scope and the HTTP endpoint. It does not disclose the consequential behavior an agent needs before calling a 17-parameter mutation — that an actual outbound message may be dispatched, that a contact may be created or updated, or that automation rules fire conditionally on the `initiator` value.

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

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

It is short and front-loaded, so there is little waste in length, but the four lines are mostly metadata scaffolding: the tag line and the raw endpoint path consume space that could have carried behavioral substance. Brevity here reflects under-specification rather than disciplined economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 high-complexity, 17-parameter, side-effecting tool with no annotations and no output schema, the description is far too thin. An agent cannot learn from it what the call actually produces or triggers, and must reconstruct that entirely from parameter docs.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters including the nuanced `initiator` and `reuse_contact` semantics. The description adds nothing about parameters beyond what the schema states, 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 only purpose statement is "Create Conversation", which is a verbatim restatement of the tool name and title. The POST path and tag add no semantic insight into what a created conversation actually contains (an initial message plus a possibly new/matched contact), and nothing distinguishes it from siblings like create_contact or create_contact_note.

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

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

There is no guidance on when to use this versus alternatives, nor any exclusions. The `conversations:write` permission note is a prerequisite, not usage guidance, and the absence of a stated condition for when a new conversation should be created leaves the agent to infer everything from the schema.

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?

No annotations are supplied, so the description must carry the whole behavioral burden. It discloses the permission requirement, the fact that filters are validated and unknown fields are refused, and the visibility semantics, which is good. It does not say what the tool returns (for example, a view ID) or whether name collisions fail, so the disclosure is incomplete for a mutation 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?

The description is front-loaded with the definition, then permissions, validation, and a worked example. It is dense but every sentence carries information. The inline JSON example makes the paragraph long, though it is justified by the nested 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 tool with nested filter objects, no output schema, and no annotations, the definition covers permissions, validation rules, scoping, and a concrete example. The only real gap is the return value, which matters if the agent must reference the new view afterward.

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

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

Schema coverage is already 100%, so the baseline is 3. The description goes beyond the schema by working through a full example payload that shows the nested rules structure, the tags 'contains' value format as a text array, and how status and tag conditions combine, which is real added meaning for a complex nested parameter.

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

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

The description gives a concrete verb and resource ('Creates a shared view') and immediately defines what a shared view is: a saved filter on the conversation list, scoped to every agent or to one team. It also draws a boundary by noting that editing and deleting happen in the web UI, so this tool cannot be confused with update_shared_view or delete_shared_view.

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

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

The description states the prerequisite (`shared_views:manage` permission) and where the tool's scope ends (editing and deleting are web-UI only). It does not name a read tool such as get_all_shared_views, but it gives a clear context for use and an explicit exclusion.

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

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

With no annotations supplied, the description carries the full burden, and it does disclose one genuinely useful behavioral fact: the required 'status:manage' scope, which tells the agent this is an authorized mutation. However, it says nothing about what happens on a duplicate name, whether the new status is immediately visible to existing conversations, or whether creation is reversible — meaningful gaps for an unannotated write 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?

The definition is four short lines and front-loads the action, permission requirement, and endpoint, which is efficient. The trailing 'Tags: Status and priority' line is categorization metadata of little value to an agent deciding how to call the tool, but it costs only a few 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?

For a two-parameter mutation with no annotations and no output schema, the definition covers purpose, endpoint, and authorization, which is the minimum an agent needs to attempt the call. It stops short of describing failure modes (duplicate names, invalid category) or what the response contains, which leaves real ambiguity for a write operation.

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

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

Schema description coverage is 100%, so the schema is the primary source of parameter meaning and the baseline of 3 applies. The description adds no additional semantics for 'name' or 'category' beyond what the schema and its enum already convey, and the schema's own 'name' description is effectively empty ('(body) ').

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

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

The description states a specific verb and resource ('Create Conversation Status') and adds the endpoint POST /api/v1/statuses, so an agent knows exactly what object is being created. It is distinguishable from delete_status and update_status by the verb alone, though it never explicitly contrasts itself with the similarly named update_conversation_status.

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

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

There is no guidance on when to create a new status versus updating an existing one (update_status / update_conversation_status), nor any note on preconditions such as name uniqueness or a status cap. The only context given is a permission prerequisite ('Requires the status:manage permission'), which is access control rather than 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?

With no annotations, the description carries the full burden. It does contribute one valuable fact — the `tags:manage` permission requirement — but says nothing about duplicate-name behavior, whether the operation is idempotent, or what the response contains. The 'POST /api/v1/tags' line and the 'Tags: Tags' line are raw spec artifacts that add no behavioral insight.

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

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

The text is short, but it is not well-curated: the bare endpoint path and the trailing 'Tags: Tags' label are noise, and the permission note is buried rather than front-loaded. The useful content is one sentence's worth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 creation tool with no output schema, the definition covers purpose and authorization, which is most of what matters. It still leaves open whether the tag is global or workspace-scoped and how a duplicate name is handled, which an agent would want before calling.

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

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

Schema coverage is 100% and the single `name` parameter is already fully documented in the schema as non-empty, so the description adds nothing here. 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?

"Create Tag" states a specific verb and resource, so the agent knows immediately this creates a new tag. There is no differentiation from siblings such as update_tag or delete_tag beyond the name itself, but the core purpose 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 description never says when to use this versus update_tag or overview_tag_distribution, nor does it mention preconditions such as checking whether the tag already exists. Usage must be inferred entirely from the name.

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

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

With no annotations supplied, the description carries the full disclosure burden, and it contributes only the `teams:manage` permission requirement and the REST endpoint. It says nothing about side effects, whether the team starts empty, validation failures, 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?

It is short and front-loaded, but much of the content is infrastructure noise ("POST /api/v1/teams", "Tags: Teams") that does not help an agent decide or invoke correctly. The one genuinely useful line, the permission requirement, is buried mid-block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 mutation with two required fields, an enum, and no output schema or annotations, the description is far too thin. An agent has no way to know what a successful response looks like, what defaults apply to timezone/SLA/business hours, or how assignment behavior is configured.

Complex tools with many parameters or behaviors need more documentation. 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 nominally 100%, so the baseline is 3; however, the actual parameter descriptions are empty placeholders like "(body)", so the schema itself adds little. The description does not clarify required fields such as name or the meaning of the "Round robin"/"Manual" conversation_assignment_type enum.

Input schemas describe structure but not intent. Descriptions should explain 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 says "Create Team," which does identify the verb and resource, but it is essentially a restatement of the tool name plus an endpoint line. It gives no indication of what kind of team object is created or how it differs from siblings like update_team or create_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 when-to-use guidance, no prerequisites beyond the permission string, and no mention of alternatives such as update_team or the related assignee tools. An agent must infer the usage context entirely from the name.

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

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

With no annotations, the description carries the full burden and does well: it discloses that deletion signs the agent out of all sessions and unassigns their open conversations, and names the required permission scope. It stops short of stating whether the deletion is irreversible, soft-delete, or what happens to historical conversation data.

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

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

Front-loaded with the action, then consequences, then permission requirement. The repeated title line and "Tags: Agents" boilerplate add minor noise, but the core sentences are tight and non-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 single-parameter destructive tool with no output schema, the description covers purpose, side effects, and auth needs, which is enough to call it correctly. Only the reversibility/aftermath of the deletion is left unstated.

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

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

Only one parameter (id), and schema description coverage is 100%, so the schema already documents it. The description adds no further meaning about the id beyond the path template already implied by the endpoint line.

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

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

States a concrete verb and resource ("Delete Agent") plus the exact endpoint DELETE /api/v1/agents/{id}, which unambiguously separates it from siblings like update_agent, get_agent, and get_agents.

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

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

Provides a prerequisite (requires the `users:manage` permission) but gives no explicit when-to-use or when-not-to-use guidance, e.g. whether a softer alternative such as update_agent or deactivating availability should be preferred before permanent deletion.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses irreversibility ("cannot be undone"), a non-obvious side effect (conversations it already acted on keep their changes), and the required permission scope. These are exactly the behavioral facts an agent needs before a destructive 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?

The destructive warning and the alternative are front-loaded ahead of boilerplate, which is the right ordering. Minor waste exists in the leading line restating the tool name and trailing metadata ("Tags: Automations") that adds nothing for an agent.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers every decision-relevant fact: permanence, residual effects, permission requirement, and the safe alternative. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% for the single `id` parameter, which the schema already labels as an automation rule ID path parameter. The description reinforces this with the `DELETE /api/v1/automations/rules/{id}` route, confirming how the ID is bound, though it adds no new constraints or ID format details.

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

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

The description states a specific verb and resource ("Permanently deletes a rule") plus the scope of the effect, making it immediately distinguishable from the non-destructive sibling `toggle_automation_rule`. An agent can select it without opening the schema.

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

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

It gives an explicit when-not and names the alternative: "To stop a rule without losing it, use `toggle_automation_rule`." Combined with the permission prerequisite (`automations:manage`), the routing decision is fully determined.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses irreversibility ('permanently'), the cascading destruction of related conversations, messages and notes, and the required `contacts:delete` permission scope, plus the underlying DELETE endpoint. It omits what happens on a missing/foreign id and what the response body contains, keeping it short of 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?

The destructive scope is front-loaded in the first sentence and there is no fluff, but the leading 'Delete Contact' restates the tool name and the trailing 'Tags: Contacts' is boilerplate that earns no 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 an irreversible one-parameter mutation with no annotations and no output schema, the description covers the essentials an agent needs: permanence, cascade effects, and the permission required. Only the return behavior and failure modes are left unstated, which is a modest gap.

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

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

Schema coverage is 100% for the single `id` path parameter, so the schema already documents it; the description's endpoint line merely reinforces that it is a path parameter. No additional meaning (id format, source of the id) is added beyond structured data.

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

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

States a specific verb and resource ('Permanently deletes the contact') and immediately scopes the blast radius to the contact's conversations, messages and notes, which implicitly separates it from narrow siblings like delete_contact_note or delete_message.

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

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

Usage is only implied — the description never says when to reach for this versus a narrower delete sibling or an alternative like block_contact, though it does state the prerequisite permission. An agent can infer the destructive-delete context but gets no explicit 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?

With no annotations, the description carries the full burden and does disclose the key traits: it is a destructive delete, it requires a named permission scope, and non-Admin callers are restricted to their own notes. It does not say whether deletion is reversible or how missing/inaccessible notes are reported, which keeps it below 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?

The definition restates itself (title line "Delete Contact Note" immediately followed by "Deletes a contact note.") and the trailing "Tags: Contact notes" adds nothing for an agent. The substantive constraints are present but not front-loaded ahead of the redundancy.

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

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

For a two-parameter destructive endpoint with no output schema, the description covers purpose, auth scope, role restriction, and the exact path, which is close to everything an agent needs to call it correctly. Reversibility and failure behavior are the only notable omissions.

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

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

Schema coverage is 100%, so both path parameters are already fully documented in the schema. The endpoint template shows where id and note_id sit in the path but adds no format or constraint meaning beyond that, warranting the 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 ("Deletes a contact note") and reinforces it with the concrete endpoint DELETE /api/v1/contacts/{id}/notes/{note_id}, which distinguishes it from deleting a whole contact. It never explicitly contrasts itself with the sibling delete_contact, so it stops short of a 5.

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

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

The permission (contact_notes:delete) and role scoping (non-Admin agents may only delete their own notes) implicitly tell the agent when the call will succeed, but there is no explicit statement of when to choose this over alternatives or when not to call it.

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

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

With no annotations, the description carries the full burden and does disclose the important trait that the handler does not check conversation access and only touches the caller's own drafts, plus the DELETE endpoint. It stops short of saying whether deletion is idempotent or what is returned on success/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?

The core scope statement and the access caveat are front-loaded and useful, but the leading line simply repeats the tool name and the trailing endpoint/tag metadata is operational filler rather than guidance for an agent.

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

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

For a two-parameter, fully-described mutation tool with no output schema, the definition covers scope, permission semantics, and the optional-parameter effect. Only the post-deletion outcome (idempotency, errors, return value) is left unaddressed.

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

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

Schema coverage is 100% and the schema already documents both parameters, including the enum values and the 'omit to delete all types' behavior. The description's restatement of the type-omission rule adds marginal value beyond the schema.

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

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

States a specific verb and resource ('Deletes the caller's draft for a conversation') and scopes it to the caller, which distinguishes it from upsert_conversation_draft and the other delete_* siblings that act on different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conditional behavior ('Without `type`, drafts of every type are deleted') implies when the optional parameter matters, but there is no explicit when-to-use guidance, no stated alternative, and no mention of what happens if no draft exists.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses that this is a soft delete (content replaced with a placeholder), that attachments are unlinked as a side effect, and that ownership/role and a specific permission gate the call. It stops short of saying whether the operation is recoverable or what happens on permission failure, which is the main remaining gap.

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

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

The core sentences are front-loaded and information-dense, but the definition spends lines on a repeated title ('Delete Message' / 'Deletes a private note'), a raw DELETE endpoint that merely restates the schema path, and a 'Tags: Conversations' footer. Those elements are structural filler rather than guidance 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 two-parameter mutation tool with no annotations and no output schema, the description covers the important unknowns: permission gate, role-based ownership rules, and the concrete effect on content and attachments. Only reversibility and result/response expectations remain unspecified, which is a minor omission at this complexity.

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

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

Schema description coverage is 100%, so both `cuuid` and `uuid` are already documented as conversation/message path parameters. The description adds no extra constraints, formats, or examples beyond what the path template and schema convey, 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 gives a specific verb and resource ('Deletes a private note') and adds concrete semantics: content replaced with a placeholder, attachments unlinked. The only wrinkle is the name/description mismatch (delete_message vs. 'private note'), which slightly muddies what exactly is removed, and there is no explicit differentiation from other delete_* siblings such as delete_contact_note.

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

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

It states clear preconditions for use: agents may delete only their own notes, Admin-role agents may delete any note, and the `messages:write_private` permission is required. It does not spell out when an agent should prefer a different operation (e.g., editing instead of deleting), so routing guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does most of it: permanence, irreversibility, that child conversations survive, the 404 behavior on wrong view type, and the required permission scope. The only real gap is the response shape for a successful delete, which is not mentioned and no output schema exists.

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

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

The body is dense and front-loaded, packing the effect, side effects, failure mode, and permission into a few lines. The duplicated "Delete Shared View" header line and the trailing "Tags: Views" add little but cost only a line each.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers effect, reversibility, permissions, and edge-case failure. Missing only the success response detail, which is a minor omission given the tool's simplicity.

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

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

Schema coverage is 100% and the single `id` parameter is already documented as the view path parameter, so the description adds nothing beyond it. Baseline 3 applies; there is no enum or ID-format guidance to add.

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

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

"Permanently deletes a shared view" gives a specific verb and resource, and the follow-on clause scopes the blast radius ("the conversations are untouched"). The endpoint and "Shared View" naming make it unambiguously distinct from the delete_contact/delete_tag/delete_team siblings.

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

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

It states a concrete exclusion ("A personal view answers 404") and a prerequisite (`shared_views:manage`), so an agent knows both the eligibility condition and the auth requirement before calling. No sibling alternative is named, but the exclusions still give clear selection 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?

With no annotations, the description carries the full burden and does well: it discloses the permission gate, the two classes of protected statuses that will cause failure, and that this is a destructive DELETE on a specific resource path. It stops short of describing the failure/response payload, which keeps it from 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?

Content is front-loaded with the action, then constraints, then the permission requirement. The trailing endpoint path and tag line are mildly boilerplate but add routing context, and there is no filler prose.

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

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

For a one-parameter destructive tool with no annotations or output schema, the description covers the essentials: what is deleted, what cannot be deleted, and the required permission. Only the behavior on failure or the expected response is unaddressed.

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

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

Schema coverage is 100% for the single `id` path parameter, so the schema already documents it. The description only repeats the path template form `{id}` and adds no meaning about the identifier's format or where to obtain it. 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 opens with a specific verb+resource ("Delete Conversation Status"), which is unambiguous. It does not explicitly distinguish itself from siblings such as update_status or create_status, but the resource is narrow enough that an agent can identify it without opening the schema.

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

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

It gives clear preconditions for use: default statuses and in-use statuses cannot be deleted, and the `status:manage` permission is required. What is missing is explicit routing to an alternative (e.g., update_status for renaming or archiving instead of deleting) when deletion is blocked.

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

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

With no annotations supplied, the description carries the full disclosure burden. It usefully states the required `tags:manage` permission scope, but gives no indication of irreversibility, whether the tag is removed from all tagged entities, or what the response looks like for a destructive operation.

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

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

Very short and front-loaded with the action name, then permission, then endpoint. The trailing 'Tags: Tags' line is a generated artifact that carries no information for an agent, but otherwise 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 single-parameter delete with no output schema and no annotations, the definition covers identity and authorization but omits the consequences of deletion (irreversibility, effect on already-tagged conversations) and any mention of error behavior for a missing id.

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

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

Only one parameter and schema description coverage is 100%, with the schema itself marking `id` as a path parameter. The description's endpoint template reinforces that the id goes in the URL path, which is a small addition, 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 title-cased phrase 'Delete Tag' names a verb and resource, and the raw endpoint 'DELETE /api/v1/tags/{id}' confirms it operates on a single tag by id. However, it essentially restates the tool name and adds nothing to distinguish it from update_tag or delete_* siblings in the catalog.

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

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

There is no when-to-use guidance, no mention that this is irreversible, no guidance on confirming before deletion, and no pointer to alternative approaches (e.g., removing a tag from a conversation instead of deleting it globally). The only conditional information is the required permission scope, which is about authorization rather than 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?

With no annotations, the description carries the full behavioral burden and does supply one useful fact: the `teams:manage` permission requirement. However, it says nothing about irreversibility, what happens to team members or assigned conversations on deletion, or whether a confirmation step exists — critical context for a destructive operation.

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

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

The definition is front-loaded and minimal: action, permission, endpoint, tag. Nothing is redundant or buried, and every line is scannable for an agent selecting a 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 one-parameter destructive tool with no output schema, the description covers identity and auth but omits the side effects an agent most needs — cascading removals, member unassignment, and irreversibility. It is callable as written but incomplete for safe 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?

Only one parameter exists and schema coverage is 100%, so the schema already documents `id` as a path parameter. The endpoint text reinforces that the id identifies the team being deleted, adding modest confirmation without contradicting the schema; baseline 4 applies for a single well-documented parameter.

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

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

The definition opens with a specific verb+resource ('Delete Team') and reinforces it with the endpoint 'DELETE /api/v1/teams/{id}', leaving no ambiguity about the operation. It does not explicitly contrast with siblings such as update_team, but the name and endpoint make the destructive scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisites beyond the permission name, and no alternatives offered (e.g., update_team or remove_team_assignee for softer changes). An agent must infer entirely from the tool name when this is appropriate versus other team operations.

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

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

With no annotations, the description carries the full load; it does add useful context by stating the required `messages:read` scope and showing that the operation is a GET (read-only) against a UUID-scoped path. It does not disclose the response format, size limits, or whether a transcript file is generated versus returned inline, which matters for a 'download' 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?

Very short and front-loaded: purpose, permission, endpoint, tags. The 'Tags: Conversations' line is auto-generated filler with no decision value, but the overall length is appropriate.

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

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

There is no output schema, so the description is the only place to learn what a 'download' yields (file format, mime type, content shape) — and it is silent on this. Permission and endpoint coverage make it minimally viable for a single-parameter tool, but an agent cannot predict the result.

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

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

Schema coverage is 100%, but the schema's only annotation is '(path parameter)', so the description partially compensates by rendering the endpoint path with {uuid}, confirming the identifier is a path segment. It adds no meaning about where the UUID comes from or what it identifies.

Input schemas describe structure but not intent. Descriptions should explain 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 name and opening line state a specific verb+resource ('Download Conversation Transcript'), which is clearly distinct from siblings like get_conversation or get_conversation_participants. However, the description adds no explicit contrast to those siblings, so differentiation is inferred from the name alone.

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

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

The only usage-relevant content is the prerequisite 'Requires the `messages:read` permission'. There is no guidance on when to download a transcript versus fetching the conversation, nor any mention of when this tool is inappropriate.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the permission requirement and HTTP GET endpoint, but does not explain export format, contents, response behavior, or any side effects beyond the implied read operation.

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

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

The description is short and front-loads the tool purpose. The raw endpoint and "Tags: Contacts" line add little value, but the overall structure is efficient.

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

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

For a simple one-parameter export tool with no output schema, the description should clarify what the export returns and how it behaves. It supplies permission and endpoint details but leaves the export result format and usage context unspecified.

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

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

Schema description coverage is 100%, so the schema already documents the single id parameter. The endpoint text `/api/v1/contacts/{id}/export` implies that id identifies the contact being exported, adding marginal meaning beyond the schema's "(path parameter)" label.

Input schemas describe structure but not intent. Descriptions should explain 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: "Export Contact Data". It is clear what the tool does, but it does not distinguish this export operation from sibling tools such as get_contact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentions a required permission, which is useful prerequisite context, but gives no guidance on when to use this tool versus alternatives like get_contact or other contact read operations. No exclusions or selection criteria are provided.

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?

No annotations exist, so the description carries the full burden, and it discloses only the permission requirement. For a credential-minting mutation it says nothing about whether an existing key is invalidated, whether the key is shown once, or whether the operation is reversible — all critical behavioral facts an agent needs.

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

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

It is short and the permission requirement sits near the top, but the leading line duplicates the tool name and the trailing "Tags: Agents" plus raw HTTP verb are auto-generated metadata rather than agent-facing guidance. Roughly half the text 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 annotations and no output schema, the definition should explain what is returned (presumably the new key) and how it relates to existing keys, and it does neither. For a security-sensitive single-parameter mutation tool this leaves an important gap despite the simple schema.

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

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

Schema coverage is 100% and the single parameter is documented only as "(path parameter)"; the route template clarifies that `id` is the agent identifier, which is a modest addition. Beyond that the description adds no format or constraint detail the schema doesn't already carry, 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 heading merely restates the tool name; the real purpose signal comes from the raw route "POST /api/v1/agents/{id}/api-key", which shows a key is minted for a specific agent. It never distinguishes itself from the sibling revoke_api_key or explains what kind of key is produced, so the agent must infer the resource relationship.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 is the prerequisite "Requires the `users:manage` permission", which is genuinely useful for deciding whether a call can succeed. There is no statement of when to use this versus revoke_api_key, no note on whether existing keys are replaced, and no mention of error behavior when permission is missing.

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?

No annotations are supplied, so the description carries the full disclosure burden. It does add real value by naming the required `users:manage` permission and the underlying REST endpoint, but it says nothing about what is returned, behavior when the id does not exist, or whether deleted/inactive agents are returned.

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

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

Four short lines with the endpoint and permission front-loaded; nothing is padded. The trailing "Tags: Agents" line is catalog metadata with no decision value, which is the only waste.

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

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

For a one-parameter read tool with no output schema, the definition covers auth and routing but leaves the response shape entirely unspecified. Since no output schema exists, a brief note on returned fields or not-found behavior would materially improve it.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents `id`. The description's `{id}` in the path template confirms it is a path parameter but adds no format, constraint, or example beyond that.

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

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

"Get Agent" alone restates the tool name, but the appended `GET /api/v1/agents/{id}` confirms this is a single-agent fetch keyed by id, implicitly distinguishing it from the list-style `get_agents`. It never explicitly contrasts with close siblings such as `get_current_agent`, so the agent must infer the distinction from the path template.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 is the `users:manage` permission requirement; there is no statement of when to call this versus `get_current_agent` or `get_agents`. An agent knowing an id is a prerequisite, but that is left implicit rather than stated.

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

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

With no annotations present, the description carries the full disclosure burden, and it does contribute one genuinely useful behavioral fact: the call requires the `users:manage` permission. However it says nothing about pagination, result volume, ordering, or what a returned agent contains, so the behavioral picture remains thin for a list endpoint.

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

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

It is short and front-loaded, but a large share of the text is scaffolding rather than meaning: the title restatement and the "Tags: Agents" line add no actionable information. The permission line is the only sentence that 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/list tool with no output schema and no annotations, the description should explain the shape and scope of what comes back and how it differs from the compact and single-agent variants. It provides neither, leaving the agent to guess at return format and sibling selection.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; per the baseline for a parameterless tool this scores at the top of the normal range. The open additionalProperties schema suggests optional query parameters may exist but are undocumented anywhere.

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

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

"Get Agents" essentially restates the tool name, and the only additional content is the raw endpoint path GET /api/v1/agents. It conveys that agents are listed, but nothing distinguishes this from siblings like get_agents_compact or get_agent, so the agent cannot tell which one 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 exclusion, and no mention of when get_agents_compact or get_agent would be preferable. The only prerequisite-like content is the permission requirement, which is not framed as a selection criterion.

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

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

With no annotations, the description carries the burden; it does disclose the auth requirement (any authenticated agent vs users:manage) and the underlying endpoint, which are genuinely useful behavioral facts. It says nothing about pagination defaults, result caps, or error behavior — though the schema covers pagination and the enum errors, the read-scope behavior is only partly covered.

Agents need to know what a tool does to the 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 payload sentence and the sibling contrast are front-loaded and each earns its place, but the leading 'Get Agents Compact' line restates the tool name and the trailing 'GET /api/v1/agents/compact / Tags: Agents' boilerplate adds little for an agent.

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

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

There is no output schema, and the description compensates by listing exactly which fields come back, plus the assignee_id follow-up use. Combined with the fully documented input schema, an agent has enough to call it correctly; only pagination/return-size behavior is left implicit.

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

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

Schema description coverage is 100%, including enum values, the 200-id cap, and the ids-overrides-other-filters rule, so the baseline is 3. The description adds no additional parameter meaning beyond naming the returned fields, which is acceptable given the schema already documents all six parameters thoroughly.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Agents and AI assistants in a short form') and enumerates the returned fields (ID, name, email, enabled, availability). It also positions the tool against the sibling get_agents by permission scope, so an agent can distinguish the two without opening either schema.

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

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

Explicitly says any authenticated agent can call it, unlike get_agents which needs users:manage, and it tells the caller what to do with the result ('Use the returned id as assignee_id of update_user_assignee'). It gives no explicit when-not-to-use case or preference rule beyond the permission difference, so it stops short of full 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?

With no annotations, the description must fully disclose behavior. It implies a read-only GET operation, but does not confirm safety, idempotency, or potential side effects. The lack of details on response format or rate limits leaves significant ambiguity.

Agents need to know what a tool does to the 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 very short, but the first line repeats the tool name. It includes the HTTP method and a tag, which is useful but not optimally structured. The brevity does not compensate for the lack of clarity; each sentence could be more informative.

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

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

Given no output schema and no annotations, the description fails to explain what the tool returns or its role in the system. Without additional context, the agent cannot determine the response structure or how 'AI prompts' relate to the broader API (e.g., ai_completion).

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

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

The tool has zero parameters, and the schema coverage is effectively 100% (empty schema). The description adds no parameter information, which is acceptable given no parameters exist. Baseline for 0 params is 4.

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

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

The description states 'Get A I Prompts' but does not clarify what AI prompts are or how they differ from sibling tools like ai_completion. The tag 'AI completions' provides a vague hint, but the purpose remains ambiguous without specifying the returned resource's nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 is provided on when to use this tool versus alternatives. There is no mention of when not to use it, or any comparison with siblings like ai_completion, get_agents, etc., leaving the agent to infer usage from the name alone.

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

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

With zero annotations, the description carries the full behavioral burden. It does add genuinely useful auth context by naming the `conversations:read_all` permission and reveals the underlying GET endpoint, which signals a safe read. But it says nothing about result volume, pagination defaults, or what an unfiltered "all" returns, which is the main risk for this 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?

It is short and the essential line comes first, with permission and endpoint following. The "Tags: Conversations" line is filler that earns no place, but there is no verbose padding to cut.

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

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

Five parameters, no annotations, and no output schema mean the description should shoulder more weight than it does. It leaves unaddressed the practical question of how to page through or scope an "all" listing, and offers no hint about the shape or size of 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%, so the schema already documents page, order, filters, order_by, and page_size in detail. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a verb and resource ("Get all Conversations") and adds the backing endpoint, but it is largely a restatement of the tool name with no scope qualifier. It never explains what "all" excludes, nor distinguishes it from the many sibling list tools such as get_assigned_conversations, get_unassigned_conversations, or get_view_conversations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-not-to-use, and no named alternative. The only usage-relevant signal is the required permission, which gates access but does not help an agent choose between this and the other conversation-listing 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?

With no annotations, the description carries the full burden, and it does disclose two useful traits: the listing is restricted to the caller's own drafts and requires authentication. It stops short of covering read-only safety, pagination/result limits, or ordering, all of which matter for a list endpoint.

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

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

The purpose is front-loaded in the first sentence with scope qualifiers following immediately. The trailing "GET /api/v1/drafts" and "Tags: Conversations" lines are metadata padding that adds little for an agent, but they are short.

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

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

For a zero-parameter read tool this covers the essentials of what is fetched and by whom. Because there is no output schema, the description should say something about the shape or volume of returned drafts (fields, pagination), and it does not.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline applies. The stated scope (all drafts, not per-conversation) is the only semantic needed, and it is present.

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

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

The description gives a specific verb and resource plus real scoping detail: unsent reply and private-note drafts, saved by the caller, across conversations. That is enough for an agent to know exactly what comes back. It doesn't name a sibling it might be confused with, but no draft-specific alternative exists in the sibling list.

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

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

"Across conversations" implies the global/my-drafts scope and "Any authenticated agent" gives an auth precondition, so usage is implied rather than stated. There is no explicit when-to-use versus when-not guidance, and no mention of when to prefer a conversation-scoped retrieval 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?

With no annotations at all, the description carries the full burden, and it does disclose two useful traits: the required `shared_views:manage` permission and the fixed sort order (most recently updated first). It omits pagination behavior and whether the result set is bounded, which matters for a list endpoint returning an unknown number of views.

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

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

The description is short and front-loaded, leading with scope and ordering before the permission note. The trailing 'GET /api/v1/shared-views' and 'Tags: Views' lines are pure metadata repetition that add no decision value.

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

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

For a zero-parameter list tool with no output schema, the definition covers scope, ordering, exclusions, and auth, but leaves the agent unable to predict the return shape or whether results are paginated. A sentence on what a shared view contains or how many are returned would close the 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?

The tool takes zero parameters, so the baseline is 4; the schema is fully self-describing and the description correctly adds nothing about parameters. One minor gap: it doesn't say whether any implicit filters (team scope) apply despite the absence of inputs.

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

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

States a specific verb and resource (get every shared view) and pins the scope precisely: views visible to all agents or one team, personal views excluded, ordered by most recent update. It's clearly distinct from the singular sibling get_shared_view, though it never names any alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context is implied rather than stated: you learn this lists shared (not personal) views, but there is no explicit guidance on when to call this versus get_shared_view for a single view, or how it differs from the conversation/draft list siblings. The permission prerequisite is the only hard gating information.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose a real operational prerequisite ('Requires the conversations:read_assigned permission') and the GET endpoint implies a read-only, non-destructive call, but it says nothing about pagination defaults, result ordering, or what happens when the user has no assigned 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?

The core sentence is front-loaded and useful, but the leading 'Get Assigned Conversations' restates the tool name and 'Tags: Conversations' is metadata noise. The raw endpoint path is mild filler given the tool name already conveys the resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five optional parameters fully covered by the schema and no output schema, the description only needs to establish scope and prerequisites, which it does. It is incomplete on return behavior — no mention of pagination envelope, default page size, or empty-result handling — which matters for a list endpoint an agent will page through.

Complex tools with many parameters or behaviors need more documentation. 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 page, page_size, order, order_by, and filters all fully documented including enum values and filter syntax, so the schema does the heavy lifting. The description adds no parameter meaning beyond that, which is the baseline expectation here.

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

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

The description states a specific verb and resource ('Get all assigned conversations') and narrows the scope to 'current user', which distinguishes it from the unassigned/team siblings in the catalog. It stops short of naming an alternative explicitly, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 scope phrase 'assigned to current user' — an agent can infer this is the tool for the caller's own queue — but there is no explicit when-to-use, when-not-to-use, or pointer to get_all_conversations / get_unassigned_conversations for other scopes.

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

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

With no annotations, the description carries the burden and does reasonably: it discloses the required `automations:manage` permission, the read-only GET endpoint, and the shape of what comes back (conditions, actions, enabled flag). It stops short of error/permission-failure behavior or whether the rule is workspace-scoped.

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

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

The core sentence is front-loaded and useful, but it is wrapped in low-value scaffolding: the title line repeats the tool name, and the raw endpoint plus 'Tags: Automations' are auto-generated noise that costs tokens without informing tool selection.

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

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

For a one-parameter read tool with no output schema, the definition covers what is needed: what is fetched, what the payload contains, and what permission is required. Only the relationship to the list tool remains unstated.

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

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

There is a single `id` parameter with 100% schema description coverage, so the schema already explains it as a path parameter. The description only restates the endpoint path and adds no format, lookup, or validation detail beyond what the schema provides — the baseline for full coverage.

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

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

States a specific verb (Get) and resource (a single automation rule) and enumerates what the response contains: conditions, actions, enabled state. That distinguishes it from the list sibling get_automation_rules by implication, 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 phrase 'A single automation rule' implies this is the detail fetch rather than the list fetch, and the permission requirement hints at a prerequisite. Beyond that there is no explicit when-to-use, no exclusion, and no pointer to get_automation_rules for enumeration.

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?

No annotations exist, so the description carries the behavior burden: it discloses the required `automations:manage` permission, the weight-based ordering, and the important edge case that an empty or unknown type returns an empty list. It doesn't cover pagination or result shape, but the core behavioral traits an agent needs are present.

Agents need to know what a tool does to the 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 definition is front-loaded with the action and ordering, then the permission requirement, then the key usage caveat. It is short and mostly earns its space, though the title restatement and raw endpoint/Tags line add some noise.

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

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

For a single-parameter list tool with no output schema, the description covers permission requirements, ordering, mandatory type, and the empty-list edge case. Pagination and response fields are unspecified, but that is a minor gap for this complexity.

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

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

Schema coverage is 100% and the enum already documents the three valid types, so the baseline is 3. The description adds useful context that the type is mandatory and that unknown types silently produce an empty list, but does not add further semantics to the single parameter.

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

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

The description gives a specific verb and resource (get automation rules), states ordering by weight, and distinguishes it from get_automation_rule by making clear this is a per-type list endpoint. The API path reinforces the intent.

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

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

It states that a type must always be passed and that empty/unknown types yield an empty list rather than all rules, which implies when the tool applies. However, it never explicitly contrasts with the singular get_automation_rule sibling or says when to choose one over the other.

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?

No annotations are supplied, so the description carries the full burden; it does disclose the required `contacts:read` permission, which is genuinely useful pre-call context. It says nothing about what the response contains, what happens for a missing or inaccessible id, or rate limits, leaving real behavioral gaps for a read tool with no 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?

Very short and front-loaded, with permission, endpoint, and tag on separate lines so the agent can scan it quickly. The opening 'Get Contact' line duplicates the tool name and earns little, but overall there is no filler.

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

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

For a simple single-resource read with one well-documented parameter, the definition is minimally sufficient: it states the operation, permission, and endpoint. With no output schema, the missing description of the returned contact object and error cases is a noticeable gap, though a moderate one for a trivial getter.

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

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

Only one parameter (id) exists and schema description coverage is 100%, so the baseline is 3. The endpoint template confirms id is a path parameter, but the description adds no format, type, or lookup semantics beyond the schema's '(path parameter)' note.

Input schemas describe structure but not intent. Descriptions should explain 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 restates the name ('Get Contact') and adds the concrete endpoint GET /api/v1/contacts/{id}, which does signal retrieval of a single contact by id. However, it never distinguishes this from the sibling get_contacts (list) or get_contact_notes, so the agent must infer the single-vs-collection distinction from the endpoint path 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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_contacts for listing or get_contact_notes for related data. The agent is left to infer selection criteria from path shape and tool names alone.

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

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

With no annotations, the description carries the full burden; it does disclose the required `contact_notes:read` permission and the HTTP route, which is genuinely useful auth context. However it says nothing about pagination, ordering, result limits, or what an empty result means for a list 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?

Three short lines, front-loaded with purpose and permission, with the routing detail after. The trailing "Tags: Contact notes" line is boilerplate that adds little, but overall there is no wasted prose.

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

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

For a simple single-parameter read tool with no output schema, the definition covers authentication and scope adequately, but omits response shape and pagination behavior, leaving an agent unable to predict what comes back.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already documents `id`. The endpoint template reinforces that `id` is the contact id rather than a note id, but no format or validity details are 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 verb+resource ("Get Contact Notes") and the underlying endpoint GET /api/v1/contacts/{id}/notes, which makes clear it lists notes scoped to a single contact. It is distinguishable from siblings like get_contact and get_contact_page_visits, though it never explicitly contrasts itself with them.

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

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

No when-to-use guidance and no mention of alternatives such as create_contact_note or delete_contact_note, nor any note about when to prefer this over fetching the full contact. The only implicit guidance is that it requires a contact 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?

With no annotations provided, the description carries the full burden and does reasonably well: it discloses the 20-item cap, newest-first ordering, the important limitation that only visits while the livechat widget was loaded are counted, and the required `conversations:read` permission. It omits error/empty behavior and raw endpoint details beyond the path.

Agents need to know what a tool does to the 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 return behavior is front-loaded in the first real sentence, with permission and endpoint metadata following. The leading line 'Get Contact Page Visits' duplicates the tool name and the Tags line is minor clutter, but the body is 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 single-parameter read tool with no output schema and no annotations, the description covers what is returned, how much, in what order, and under what data-collection condition, plus the auth requirement. An agent has enough to call it correctly; only empty-result and error semantics are unaddressed.

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

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

There is one parameter with 100% schema description coverage, so the schema already explains that uuid is the conversation UUID path parameter. The description's phrase 'the conversation's contact' only loosely reinforces that the UUID scopes to a conversation, adding little 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 ('Returns the last 20 website pages the conversation's contact visited') and adds scope detail (newest first, widget-loaded only). It does not explicitly contrast itself with siblings like get_contact or get_conversation, so it stops short of full differentiation.

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

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

The description implies usage by framing the data as tied to a livechat widget and requires a specific permission, but it never says when to prefer this over alternatives or what conditions make it inapplicable (e.g., contacts without widget history). Guidance is 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?

With no annotations supplied, the description carries the full behavioral burden and does add one genuinely useful fact: the required `contacts:read_all` permission scope. It stops there, saying nothing about read-only semantics, rate limits, result size, or pagination behavior beyond what the schema already encodes.

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

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

Very short and front-loaded, with the permission requirement placed early. The trailing "Tags: Contacts" line is metadata noise that does not help an agent decide or call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five-parameter list tool with no output schema and no annotations, the definition is thin: it never states what a contact record looks like or whether results are paginated beyond the page parameters. The permission note is the only substantive addition beyond the schema.

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

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

Schema description coverage is 100%, so page, page_size, order, order_by and the JSON filters parameter are all fully documented in the schema itself. The description adds no parameter meaning at all, which is acceptable only because 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 verb and resource ("Get Contacts") and confirms it via the endpoint GET /api/v1/contacts, so an agent can tell this is a read/list operation. However, it never distinguishes itself from siblings like search_contacts or get_contact, leaving the exact scope (full list vs. single record vs. filtered search) 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?

There is no when-to-use guidance and no mention of any alternative tool. The agent must guess whether to call this or search_contacts when looking for a specific contact.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioral trait: the required `conversations:read` permission scope. However, it says nothing about whether fetching marks the conversation as read, what the response contains, or how missing/invalid UUIDs behave — meaningful gaps for a read tool with zero 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?

The content is short and front-loaded, and the permission requirement appears early. The 'Tags: Conversations' line and the raw HTTP endpoint are boilerplate that adds little for an agent, but the overall size is appropriate.

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

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

Complexity is low (one required parameter, no nested objects), and the permission plus endpoint give the essential call mechanics. But with no output schema and no annotations, the description is the only place the return value or side effects could be described, and it omits both.

Complex tools with many parameters or behaviors need more documentation. 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 `uuid` parameter is documented as a conversation UUID path parameter, so the schema does the work. The description adds nothing beyond that, which is the expected baseline rather than a strength.

Input schemas describe structure but not intent. Descriptions should explain 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 name/title is merely restated as 'Get Conversation', but the endpoint GET /api/v1/conversations/{uuid} makes clear this retrieves a single conversation by UUID. It does not distinguish this from siblings like get_all_conversations or get_mentioned_conversations, so an agent must infer the single-vs-list distinction from naming 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?

There is no when-to-use guidance and no mention of alternatives; the only condition stated is the required `conversations:read` permission. An agent gets no help deciding between this and list-style siblings such as get_all_conversations or get_contact.

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

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

With no annotations, the description carries the behavioral burden; it usefully discloses the required `conversations:read` permission and the read-only GET endpoint, which an agent cannot infer from the schema. It says nothing about pagination, result ordering, or what happens when a conversation has no participants.

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

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

It is short and front-loads the operation, but the first line merely repeats the tool name and the 'Tags: Conversations' line is raw API metadata with no value to an agent. A single sentence stating the operation, resource scope, and permission would have been tighter.

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

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

For a single-parameter read tool with no output schema, the definition covers the permission requirement and endpoint, which is a reasonable minimum. It leaves the agent guessing about the response shape (list of participant objects?) and whether results are paged.

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

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

Schema coverage is 100%, so the uuid parameter is fully documented in the schema itself, and the description adds only that it is a path parameter via the endpoint template. Baseline 3 applies since the description contributes little beyond structured data.

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

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

The description states a specific verb and resource ('Get Conversation Participants'), and the endpoint path confirms it reads the participants sub-collection of one conversation. It is distinguishable from the broader get_conversation sibling, though it largely echoes the tool name.

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

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

No guidance is given on when to call this versus get_conversation or other conversation tools. The only contextual cue is the required permission, which implies reading rather than mutation but does not establish usage conditions or 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?

No annotations provided, so description carries full burden. It does not disclose behavioral traits such as whether it requires authentication, what data is returned, or side effects. Essentially opaque.

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

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

Extremely concise but at the cost of informativeness. It provides only the name, endpoint, and tags, which is too minimal to be helpful. Lacks key context that an agent would need to correctly invoke the tool.

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

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

Given no parameters, no output schema, and no annotations, the description should compensate with context. It does not explain what 'current agent' means, how to interpret the response, or prerequisites. Incomplete for a tool with zero structured guidance.

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

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

No parameters exist, so schema coverage is 100% trivially. Description adds no additional meaning beyond the schema, but baseline is 3 as the schema already covers all parameter aspects.

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

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

The description clearly states 'Get Current Agent', which conveys the verb and resource. It distinguishes from siblings like 'get_agent' (requires ID) and 'get_agents' (list all), but does not explicitly explain 'current' meaning the authenticated agent. Slight ambiguity but sufficient.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use this tool versus siblings. The description does not mention when to prefer this over get_agent or get_agents, nor does it provide context for typical usage scenarios.

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?

No annotations are supplied, so the description carries the full behavioral burden. It implies a read via the GET endpoint, but says nothing about authentication needs, result ordering, pagination, or what fields an attribute record contains — substantial gaps for an unannotated 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?

It is short and front-loaded, but the 'GET /api/v1/custom-attributes' and 'Tags: Custom attributes' lines are API-doc boilerplate that gives an agent little it can act on. Size is fine; content density is low.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 listing tool with no output schema and no annotations, the description should say what an attribute looks like and whether results are paginated or complete. Neither is covered, leaving the agent to discover the response shape by trial.

Complex tools with many parameters or behaviors need more documentation. 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 optional 'applies_to' filter is fully documented in the schema, including the empty-value behavior. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

The description says 'List Custom Attributes' and gives the underlying endpoint GET /api/v1/custom-attributes, so the verb and resource are identifiable. However, it largely restates the tool name and adds no scope detail (all attributes? per workspace?) nor any distinction from the sibling update_*_custom_attributes tools that operate on the same resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 call this versus the sibling update_contact_custom_attributes / update_conversation_custom_attributes tools, and no stated preconditions. The only usage-like hint ('Returns all when empty') lives in the parameter 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?

With no annotations present the description carries the full burden, and it does disclose two non-obvious behaviors: credential fields in `config` are masked in the response, and a privileged scope is required. It doesn't describe error behavior for a missing or unauthorized ID, but the key surprises are surfaced.

Agents need to know what a tool does to the 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 masking warning and permission note are front-loaded and worth their space. The leading "Get Inbox" heading restating the tool name and the trailing "Tags: Inboxes" / raw route line are generated boilerplate that adds no decision value.

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

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

For a single-parameter read with no output schema, the description covers identity, scope requirement, and response masking — enough to call it correctly. Only error and not-found semantics are absent.

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

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

Schema coverage is 100% and the single `id` parameter is already documented as an integer path parameter. The description's "by ID" adds no syntax or format detail 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?

Description gives a specific verb and resource ("A single inbox by ID") and explicitly contrasts with the sibling list route ("Unlike the inbox list"). An agent can distinguish this from get_inboxes without inspecting either schema.

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

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

It supplies a real decision-relevant condition: this route requires the `inboxes:manage` permission, implicitly steering unprivileged callers to the list endpoint. It stops short of naming get_inboxes as the explicit fallback, so the routing 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?

No annotations are supplied, so the description carries the full disclosure burden, yet it does nothing beyond restating the name plus a raw endpoint path. It says nothing about what an inbox record contains, whether results are paginated or filtered by account/workspace, or what permissions are needed.

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

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

It is short and front-loads the meaningful part ("List Inboxes"). The trailing "Tags: Inboxes" line is generated-doc boilerplate that adds nothing for an agent, and the raw path is of marginal use.

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

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

For a zero-parameter tool with no annotations and no output schema, the description should at least characterize the returned list, but it never does. An agent knows it lists inboxes and nothing more, which is thin given no other structured field carries that information.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies no inputs are required.

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

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

"List Inboxes" states a specific verb (list) and resource (inboxes), so the operation is unambiguous. It does not differentiate itself from the singular sibling get_inbox, leaving the agent to infer the difference from names alone.

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

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

There is no when-to-use guidance, no mention of the singular get_inbox alternative, and no stated prerequisites. The only hint is the bare REST path GET /api/v1/inboxes, which implies a read of the inbox collection but gives no selection 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?

No annotations are supplied, so the description carries the full behavioral burden, and it does add meaningful context: any authenticated agent may call it and the macro's visibility is NOT checked on this route, which is a real security-relevant disclosure the schema cannot convey. It also states the response includes message content and actions; it omits not-found/error behavior and any pagination or rate-limit notes.

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

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

The content is short, but it is padded with API-doc boilerplate — a redundant title line 'Get Macro', the raw route, and 'Tags: Macros' — none of which help an agent select or invoke the tool. The most valuable sentence (visibility not checked) is buried after the 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?

For a one-parameter single-record getter with no output schema, the description covers what the tool returns (message content and actions) and the auth/visibility caveat, which is enough to call it correctly. Only error behavior on an unknown ID is left unstated, a minor gap for a tool of this complexity.

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

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

There is a single parameter with 100% schema description coverage ('Macro ID (path parameter)'), so the schema already carries everything needed. The description's GET /api/v1/macros/{id} merely restates that id is a path segment, adding no new meaning such as ID format or source.

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

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

The description names a specific verb and resource ('Get Macro ... A single macro') and clarifies the payload ('its message content and its actions'), which distinguishes it from the list-style sibling get_macros. It stops short of naming the sibling explicitly, so differentiation is implied rather than stated.

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

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

There is no explicit 'use this when...' or comparison to alternatives such as get_macros or get_macros_compact. Usage is only implied by the wording 'A single macro' plus the REST path with an {id} path parameter, which tells an agent this is a by-ID lookup.

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

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

With no annotations, the description carries the full burden; it does disclose the auth prerequisite and describes the returned structure (message content plus action targets), and "Every macro" implies an unfiltered full result set. It stops short of covering size/pagination behavior or rate limits for what is clearly a bulky payload, and the existence of a "compact" sibling is the only hint about cost.

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

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

Front-loaded with the resource and payload shape, then alternatives — efficient and well ordered. The trailing "GET /api/v1/macros" and "Tags: Macros" lines are transport metadata that add no selection value for an agent.

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

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

For a zero-parameter read tool with no output schema and no annotations, the definition covers what comes back (message content, actions with `display_value`) and who may call it. Missing only secondary details such as result ordering or any server-side limits on the list size.

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

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

The tool takes zero parameters and the description adds nothing parameter-related, which is the correct baseline of 4. The noted schema coverage of 100% is trivially true for an empty object 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 (Get) and resource (Macros) and then characterizes the payload precisely: every macro with message content plus actions, where each action carries `display_value` naming the team/agent/status/priority it targets. It also implicitly distinguishes itself from `get_macros_compact` and `search_macros`, so an agent can tell them apart without opening schemas.

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

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

Explicitly routes the agent: use `search_macros` to list only macros the caller may apply, and `get_macros_compact` for a list without message content. It also states the access condition ("Any authenticated agent"). The only gap is it never says when this heavy full-content variant is the wrong default.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the `has_message_content` flag, the newest-updated-first ordering, the page_size=0/absent returns-everything behavior, and the `macros:manage` permission requirement. It stops short of describing the return shape or any rate/volume 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?

The substance is front-loaded and dense — scope, flag, sort, pagination and permission in a few clauses. It is slightly padded by the redundant title echo 'Get Macros Compact' and the trailing 'GET /api/v1/macros/compact' / 'Tags: Macros' boilerplate.

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

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

For a simple three-parameter read tool with fully documented schema and no output schema, the definition covers the operationally risky bits: permission requirement, default ordering, and the unbounded-result mode when page_size is 0. What comes back per macro is not described, but no output schema exists to lean on.

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

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

Schema coverage is 100%, so q, page and page_size are already documented in the schema, establishing a baseline of 3. The description restates the page_size=0 semantics and adds the default sort order, but contributes no new parameter meaning beyond the schema.

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

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

States a specific verb and resource ('Get Macros Compact') plus concrete scope: macros without message content, filtered by name, newest update first. It implies a content-bearing sibling via 'without their message content' but never names get_macros or search_macros, so differentiation 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?

Usage is only implied: 'macros without their message content' suggests picking this over a full-content variant when the body isn't needed. There is no explicit when-to-use, when-not-to-use, or named alternative among get_macros / search_macros / get_macro.

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

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

With no annotations supplied, the description carries the burden and does well: it discloses the required `conversations:read` permission, implies a read-only GET endpoint, and tells the agent that each item carries a `mentioned_message_uuid` pointing at the mention. It does not cover pagination limits or response shape, but those are partly in the schema.

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

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

The body is three tight sentences front-loaded with the defining scope. The leading line restating the tool name is redundant, a small waste in an otherwise efficient definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five-parameter read tool with no annotations and no output schema, the description supplies the essential extras: the permission requirement and the field that identifies the mention. Only the return envelope and pagination behavior remain undocumented, which the schema largely covers.

Complex tools with many parameters or behaviors need more documentation. 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 defaults, enums, and the full filter grammar documented in the input schema. The description adds nothing about parameters, which is acceptable given the schema does the work, but earns only the baseline.

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

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

The description names a specific verb and resource plus a precise scope: conversations where the current user or their team was mentioned in a private note. That scope alone distinguishes it from siblings such as get_all_conversations and get_assigned_conversations without opening either schema.

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

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

The mention-based filter gives clear context for when this tool is the right choice rather than a general listing tool. It stops short of explicitly naming an alternative for the broader case or stating exclusions, so it lands at a solid 4 rather than 5.

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

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

No annotations are supplied, so the description carries the full burden. It usefully discloses the `messages:read` auth requirement and the endpoint, but says nothing about the response contents, error behavior for a missing or malformed UUID, or confirmation that it is a non-mutating read. The Tags line adds no behavioral value.

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

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

Very short and front-loaded with purpose, permission, and endpoint. The 'Get Message' heading restating the name and the Tags line are mildly redundant, but nothing impedes comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-UUID tool the essentials are nearly there, but with no annotations and no output schema the description should indicate what a successful response contains or what failure looks like. Auth is covered; return and error behavior are not.

Complex tools with many parameters or behaviors need more documentation. 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 are documented as path parameters. The endpoint template reinforces which parameter is which, but adds no format or constraint 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+resource (get a message), with the REST path confirming the exact endpoint. It is implicitly distinguishable from plural siblings like get_messages via the singular name, but the description does not call out 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?

No when-to-use guidance, alternatives, or exclusions are provided. The required permission is a prerequisite, not usage guidance. An agent must infer from the path template that this fetches one specific message by conversation UUID and message UUID.

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

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

With no annotations, the description carries the full burden, and it does disclose two useful facts: the GET method (implying a read-only, side-effect-free call) and the required `messages:read` permission. It says nothing about result ordering, total counts, or pagination envelope even though page/page_size exist, and 'Tags: Conversations' is metadata rather than 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?

Very short and skimmable, with the permission requirement front-loaded after the title. Some content is raw spec residue (the literal endpoint path and 'Tags: Conversations') that provides little decision value, but there is no verbosity to penalize.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 paginated, filterable listing tool with no annotations and no output schema, the description leaves too much open: return shape, ordering, and how this differs from sibling message-retrieval tools are all absent. The permission line is useful but insufficient on its own.

Complex tools with many parameters or behaviors need more documentation. 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 uuid, page, page_size, type, and private are all documented in the schema itself. The description adds no meaning beyond that—for example, no note on default sort order or how filters combine—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 gives the resource ('Messages') and the endpoint path GET /api/v1/conversations/{uuid}/messages, which together imply 'list messages in a conversation'. But 'Get Messages' largely restates the tool name, and it never distinguishes this listing tool from siblings like get_message, search_messages, or paginated_search_messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the sibling search/listing tools, nor any prerequisite or exclusion beyond the permission requirement. The agent must infer usage from the name and endpoint 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?

No annotations provided, and the description only includes 'GET /api/v1/priorities' and tags, which implies read-only behavior but does not disclose response format, authentication needs, or any other behavioral traits.

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

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

Extremely concise with just two lines, front-loading the purpose. However, it could include a brief sentence on what the response contains without increasing length much.

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

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

For a parameterless GET endpoint, the description minimally explains the purpose but omits what the output looks like. Without an output schema, more context on return values would be helpful.

Complex tools with many parameters or behaviors need more documentation. 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 has no parameters with 100% coverage, so the description adds no parameter information. Baseline 3 is appropriate as no further detail is needed.

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

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

The description states 'Get Conversation Priorities' which clearly identifies the verb (Get) and resource (Priorities), distinguishing it from sibling tools like 'update_conversation_priority' or 'get_statuses'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use this tool versus alternatives. Does not specify that it retrieves the list of available priorities, not conversation-level assignments.

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?

No annotations are supplied, so the description carries the full behavioral burden. The word 'public' hints that no authentication is required, but the description says nothing about what a successful response contains, whether unpublished or missing articles error out, or how locale fallback behaves at the result level.

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

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

It is short and front-loaded with the operation name, so there is little bloat. However, the raw route line and the 'Tags: Help center' line are API-spec artifacts that consume space without helping an agent decide or invoke.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 annotations and no output schema, the description is the only source of behavioral information, and it does not say what the tool returns (article body, title, metadata) or how failures manifest. For a tool with a required path pair and an optional locale, this leaves notable gaps.

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

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

Schema description coverage is 100%, with each parameter documented as a path or query parameter, so the baseline is 3. The description adds no meaning beyond the schema — it names no parameter semantics, formats, or constraints.

Input schemas describe structure but not intent. Descriptions should explain 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 is largely a restatement of the tool name: 'Get Public Help Center Article' plus the raw HTTP route GET /api/v1/public/help-centers/{slug}/articles/{article_slug}. The route does imply a single-article fetch scoped by help center, but nothing distinguishes it from siblings like public_help_center_search or get_public_help_center_tree beyond the URL shape.

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

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

There is no statement of when to use this tool rather than searching or fetching the help center tree. An agent must infer usage entirely from the name and path, and no exclusions, prerequisites, or alternatives are named.

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?

No annotations are supplied, so the description must carry the full behavioral burden and it does not. The GET verb and /public/ prefix hint at a read-only, unauthenticated endpoint, but nothing states the access model, whether unpublished content is excluded, pagination, or response shape.

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

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

It is short and front-loaded with the tool name, but the content is largely a restatement of the name plus a raw endpoint and an autogenerated tag. Low information density rather than verbal bloat keeps it in the middle of the scale.

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

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

This is a public discovery tool with no output schema and no annotations, so the description is the only place to explain what a "tree" contains (categories, nested articles, ordering, depth). None of that is present, leaving the agent unable to predict the return value.

Complex tools with many parameters or behaviors need more documentation. 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 (slug, locale) are documented in the schema, so baseline 3 applies. The URL template mildly reinforces that slug is a path parameter, but the description adds no new meaning, such as slug validation or locale fallback behavior.

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

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

The definition names a verb and resource ("Get Public Help Center Tree") and pins it to a concrete endpoint, so the agent knows it retrieves a help center's hierarchical structure. However, "tree" is never explained, and it offers no differentiation from siblings such as get_public_help_center_article or public_help_center_search. It sits at vague-but-recognizable rather than specific.

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

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

There is no when-to-use or when-not-to-use guidance at all; the only context is the HTTP route and a "Help center" tag. An agent cannot tell from this text whether to reach for the tree endpoint versus the article endpoint or the public search tool.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses the permission requirement, the 404 behavior for personal views, and the exact endpoint (GET /api/v1/shared-views/{id}). The main omission is any hint about the response payload beyond 'with its filters,' which matters 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?

Short and front-loaded: the core definition comes first, followed by the constraint and the endpoint. The repeated title line ('Get Shared View') and the trailing 'Tags: Views' are low-value padding but not distracting.

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

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

For a one-parameter read tool with no output schema, the definition covers the important ground: what is returned conceptually, who can call it, and what happens on a personal view. Only the shape of the returned view object is left unspecified, a minor gap for a tool this simple.

Complex tools with many parameters or behaviors need more documentation. 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, which already labels it as the view ID path parameter. The description adds no format, range, or sourcing guidance for that ID, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get Shared View / A single shared view with its filters.' The word 'single' implicitly distinguishes it from the list-style sibling get_all_shared_views, though that sibling is never named. An agent can identify the operation without opening the schema.

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

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

Gives a clear precondition and a negative case: 'A personal view answers 404,' which tells the agent this tool only serves shared views. It also states the required `shared_views:manage` permission. It does not explicitly name alternatives such as get_all_shared_views, so routing is inferred 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?

With no annotations, the description carries the full burden and does well: it discloses caller-only scoping, the required conversations:read permission, and a non-obvious behavioral trait — per-view counts are scan-capped at 100 (UI renders 99+). It omits the concrete response shape, but most safety/scope concerns are covered.

Agents need to know what a tool does to the 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 scoping and count list are front-loaded and earn their place, but the first line merely restates the title, and the raw method/path and 'Tags: Conversations' lines are low-value metadata noise for an agent choosing a tool.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description covers purpose, scope, permission requirement, and a subtle cap behavior. Only the concrete field names of the returned counts are left unspecified.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it does not mislead about inputs.

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

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

States a specific verb+resource (sidebar counts) and enumerates exactly which counts are returned: assigned, mentioned, unassigned, all, plus per-view counts for personal and team-shared views. It does not explicitly distinguish itself from the sibling overview_counts, so an agent must 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?

Usage is implied by 'inbox sidebar badges of the caller' — a caller-scoped badge endpoint — but there is no explicit when-to-use statement, no condition distinguishing it from overview_counts or get_assigned_conversations, and no exclusions.

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

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

No annotations exist, so the description must disclose behavior. It only indicates 'Get' (read-only) but fails to mention side effects, rate limits, or return format, leaving significant gaps.

Agents need to know what a tool does to the 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 very short but includes extraneous URL and tags. It could be more concise by focusing only on the operation, e.g., 'Get Conversation Statuses'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 retrieval tool with no output schema, the description should at least hint at what is returned (e.g., list of status objects). It also fails to differentiate from 'get_priorities', leaving the agent underinformed.

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

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

The input schema has no parameters, so schema coverage is 100%. The description adds no value beyond the schema, but given zero parameters, a baseline score of 3 is appropriate.

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

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

The description clearly states 'Get Conversation Statuses', identifying the verb and resource. However, it lacks differentiation from sibling tools like 'get_priorities', which may reduce clarity for 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?

No usage guidelines are provided. The description does not mention when to use this tool versus alternatives like 'get_priorities' or any prerequisites.

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

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

No annotations are supplied, so the description carries the full disclosure burden, yet it only adds the sort order. It says nothing about authentication needs, rate limits, whether the call is read-only, or how paging behaves when combined with filtering — the schema hints at the last point but the description does not.

Agents need to know what a tool does to the 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 definition is short and front-loads the verb, with the sort-order note immediately useful. The trailing 'Tags: Tags' line is redundant noise that earns no 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 with four fully documented optional parameters, the essential mechanics are covered by the schema. However, with no output schema and no annotations, the description should at least sketch the returned tag shape or whether all tags are returned by default.

Complex tools with many parameters or behaviors need more documentation. 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 q, ids, page, and page_size all documented including precedence rules for ids. The description adds no parameter 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?

The description states a specific verb and resource ('List Tags') and adds that results are sorted by name, so an agent knows exactly what the tool returns. It does not differentiate from any sibling, but no sibling in the provided list plausibly competes for the same resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, no prerequisites, and no mention of alternatives for retrieving tag data. The agent must infer that this is the only tag-listing call.

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?

No annotations are supplied, so the description carries the full behavioral burden. It does disclose one genuinely useful trait beyond the schema — that the `teams:manage` permission is required — and the GET verb implies a non-mutating read, but it says nothing about the response shape, error/404 behavior, or whether the permission scope is broader than a read strictly needs.

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

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

It is short and the key facts (operation, permission, endpoint) come first. The trailing 'Tags: Teams' line is API-doc boilerplate that adds nothing for an agent, but the overall footprint is small and there is no redundant prose.

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

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

For a one-parameter read of a single resource with full schema coverage and no output schema, the definition covers the essentials: what it returns conceptually, the endpoint, and the permission gate. The missing piece is failure behavior and any relationship to the list-level or mutation siblings, which keeps 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 coverage is 100% for the single `id` path parameter, so the schema already carries the semantics. The description only echoes it via the endpoint template '{id}' and adds no format, source, or validation details beyond what the schema states.

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

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

The description pairs the verb 'Get' with the resource 'Team' and disambiguates the scope with the endpoint 'GET /api/v1/teams/{id}', making clear it fetches a single team by id rather than a list. It stops short of naming any sibling (e.g. update_team, delete_team) as a contrast, so differentiation is only implicit through the HTTP verb.

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