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

Annotations already declare the mutation profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive). The description adds genuinely important behavioral context the annotations cannot: the endpoint is undocumented and may be changed or removed without notice, with no documented equivalent. That is exactly the kind of stability risk an agent should know before calling it.

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

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

Two short sentences, front-loaded with the purpose and followed by the one caveat that matters. No redundancy or 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining gap is the un-documented parameter set for a mutation tool, which the description does not compensate for. Adequate but incomplete.

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

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

Schema description coverage is 0% across six parameters, so the schema lists only names and types. The description adds no field-level meaning whatsoever (required name, optional address/city/state/country/zipcode formats), leaving the agent with no semantic guidance beyond raw field names.

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

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

States a specific verb+resource ('Create a new client record'), clearly separating it from sibling read/update/delete client tools. It doesn't explicitly name siblings, but the operation is unambiguous.

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

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

The description implies creation of a standalone client record, and it usefully cautions that the route is undocumented. However, it gives no explicit when-to-use vs use-an-alternative guidance (e.g., when to use create_client_contact instead), leaving usage to inference.

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

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

Annotations already declare non-read-only, open-world, non-idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new and important context beyond that: the underlying route is undocumented and Smartsheet may change or remove it without notice. It stops short of saying what happens on duplicate contacts or whether the contact is immediately visible in list endpoints.

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

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

Two short sentences with the core action front-loaded and the caveat following. Every sentence earns its place, though the API-reference and archived-docs detail is slightly verbose for what amounts to 'undocumented endpoint'.

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

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

An output schema exists, so return values needn't be explained, and the undocumented-route warning is a useful completeness addition. But for a six-parameter creation tool with zero schema descriptions, the absence of any field semantics leaves the definition short of what an agent needs to populate a call correctly.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden and says nothing about email, phone, title, or whether client_id accepts an integer or a string. It doesn't even note that first_name and last_name are required. The one line of description text is entirely about the endpoint, not the 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: 'Add a contact for a client.' This clearly distinguishes it from admin_update_client_contact, admin_delete_client_contact and admin_list_client_contacts, though it never names those siblings explicitly. The noun/verb pairing leaves no ambiguity about what the tool does.

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

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

No guidance on when to use this versus the sibling contact tools or when to prefer creating a contact on a client record. The only routing-adjacent statement is 'No documented equivalent was found', which is a provenance note rather than usage guidance. Prerequisites such as needing an existing client are left implicit.

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

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

Annotations already declare the mutation profile: readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds the allowed field/target types but does not disclose permissions, side effects, or the relationship between field_type='select' and the optional options parameter.

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

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

A single front-loaded sentence with a compact parenthetical list. There is no filler, and the most important information appears first.

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

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

An output schema exists, and annotations cover the safety profile, so return values need not be described. However, with 0% schema coverage and missing usage/parameter details, the description is only moderately complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It supplies allowed values for field_type and target_type, which the schema does not, but it leaves required 'name' and optional 'options' undocumented, including when options should be used.

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

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

The description states a specific verb and resource: 'Create a custom field definition.' It also enumerates allowed values for field_type and target_type, making the tool's purpose unambiguous against list/get/update/delete 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?

No when-to-use guidance is provided. It does not mention alternatives such as admin_update_custom_field or admin_list_custom_fields, nor any prerequisites or conditions for creating a custom field.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, non-idempotent), and the description adds genuinely new behavioral context: the POST /disciplines route is undocumented and subject to unannounced change or removal. That is exactly the kind of risk an agent can't get from structured fields. It doesn't cover auth requirements or duplicate-name behavior, keeping it below 5.

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

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

Two short paragraphs, front-loaded with the action, followed by the operational caveat. The second paragraph is slightly long for the warning but every clause is substantive and none is 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?

An output schema exists so return values needn't be explained, and the undocumented-route risk is covered, which are the two biggest gaps. However, for a mutation tool with a single undocumented parameter, the definition omits what a successful create returns in practice (new ID availability), permission requirements, and duplicate handling — leaving it only minimally sufficient.

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

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

Only one parameter (name, required) with 0% schema description coverage, so the description carries the full burden of explaining it — yet it says nothing about format, length, uniqueness constraints, or whether the name is a free-text label or a lookup key. An agent must guess at valid input.

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

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

The first sentence gives a specific verb and resource (create a discipline), which is unambiguous and distinguishable from admin_update_discipline, admin_delete_discipline, and admin_list_disciplines by name. It stops short of explicitly contrasting with those siblings, so it lands at a clear 4 rather than 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?

Nothing states when to create a discipline versus update an existing one, what prerequisites exist (permissions, whether the discipline must be unique), or what to do if the name already exists. The only contextual guidance is a stability warning about the underlying route, not about usage selection.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent write, so the safety profile is covered. The description adds genuinely new behavioral context: it discloses that the route it uses is undocumented and may be changed or removed without notice, and names the documented alternative endpoint. It could go further (e.g., that retrying a non-idempotent create may duplicate expenses) but it materially exceeds the annotation bar.

Agents need to know what a tool does to the 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, front-loaded sentences with no filler, and the purpose statement leads. The bulk of the text is devoted to route provenance rather than call-relevant behavior, which is slightly off-balance 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?

Return values are covered by the output schema and the mutation safety by annotations, but for a 7-parameter create tool with zero schema descriptions the definition leaves the agent without any parameter-level guidance. An agent could not confidently supply date/amount/category values from this description alone.

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

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

Schema description coverage is 0% across 7 parameters (5 required), so the description must compensate and it does not. No mention of date format, whether amount is in a specific currency, what expense_category_id accepts, or that user_id/project_id accept either integers or strings. Only the route template faintly implies user_id identifies the expense owner.

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

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

"Log a project expense item" states a specific verb (log/create) and resource (project expense item), which distinguishes it from the sibling list/get/update/delete expense tools. It does not distinguish it further from other create-type admin tools, but the verb+resource pair 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 create an expense versus using admin_update_expense or admin_create_expense_category, nor does it state prerequisites such as the project/category needing to exist or the caller needing admin rights. The route discussion is implementation trivia, not usage guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds genuine value by disclosing that the endpoint is undocumented and may change or be removed without notice, which is context annotations cannot convey. It stops short of describing what happens on duplicate names or the required permissions.

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

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

The action is front-loaded in a single short sentence, and the caveat paragraph is short and clearly separated. The API reference detail is somewhat inside-baseball but earns its place as a warning about tool stability.

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

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

An output schema exists, so return values need not be explained, and this is a one-parameter tool. However, for a creation tool the description omits error behavior (duplicates) and parameter constraints, leaving gaps an agent would hit when actually invoking it.

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

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

Schema coverage is 0% and the single required parameter 'name' has no description in the schema. The description says nothing about name constraints, uniqueness, length limits, or format, so it fails to compensate for the coverage gap on the one parameter that matters.

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

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

The first sentence states a specific verb and resource ('Create an expense category'), which distinguishes it from admin_create_expense and admin_delete_expense_category by the resource being created. It does not explicitly name or differentiate from those siblings, but the resource name is unambiguous.

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

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

There is no guidance on when to create a category versus using an existing one, nor any pointer to admin_list_expense_categories to check for duplicates before creating. The only conditional content is an API-stability warning, which is not usage guidance.

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

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

Annotations already declare openWorldHint=true, idempotentHint=false and destructiveHint=false, but the description adds genuinely new context: the POST /holidays route is undocumented and may be changed or removed without notice. That is exactly the kind of operational caveat annotations cannot carry. It does not mention duplicate-handling or conflict behavior on repeat calls, 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?

Two sentences, front-loaded with the action statement and followed by the one caveat that matters. No repetition of the title or schema, and nothing an agent would skip.

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

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

An output schema exists, so return values need no explanation, and the undocumented-route warning covers the biggest behavioral risk. However, for a mutating create tool with zero parameter documentation, the absence of any date/end_date semantics leaves a real gap an agent would hit on first invocation.

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

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

Schema description coverage is 0% across three parameters, and the description supplies nothing: no date format, no explanation of how end_date changes the semantics from single day to range, no hint that name is a display label. With the schema doing none of the work, the description should compensate and does not.

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

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

The opening sentence gives a specific verb and resource ("Create a new company holiday or non-working day"), which cleanly separates it from the list/get/update/delete holiday siblings. It stops short of naming those siblings explicitly, so an agent must infer the distinction, but the verb+resource pairing 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?

It never says when to reach for this versus admin_update_holiday or admin_list_holidays, nor what prerequisites (admin scope, existing calendar) apply. The only guidance offered is a warning about the route's undocumented status, which is about risk, not about tool selection.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the write/non-idempotent profile is covered. The description adds a genuinely useful warning beyond the annotations: the backing route is undocumented and subject to change or removal without notice, which tells the agent this call carries instability risk. It still doesn't mention required permissions or what happens on a duplicate name.

Agents need to know what a tool does to the 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, followed by a risk caveat that earns its place. Two short sentences with no filler, though the route-path detail is more implementation trivia than agent-facing guidance.

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

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

An output schema exists, so return values needn't be explained, and the annotations plus the undocumented-route warning cover the safety and stability profile. Missing are permission requirements, uniqueness behavior on the name field, and any note on how the new type relates to existing leave types – meaningful gaps for a mutation tool.

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

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

Schema description coverage is 0% for the single parameter 'name', and the description says nothing about it. It doesn't state whether the name must be unique, whether it's case-sensitive, or any length/format constraints, so it fails to compensate for the schema gap.

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

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

States a specific verb and resource ('Create a new leave type'), which is unambiguous against siblings like admin_update_leave_type and admin_delete_leave_type by name alone. It stops short of explicitly differentiating itself from the other admin_* create tools, but the purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 admin_update_leave_type or when a leave type should be created at all. No prerequisites, no alternatives, no exclusions are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured context: this hits an undocumented POST /roles endpoint outside the published reference and may change or disappear without notice – a real operational risk an agent should know. It omits duplicate-name behavior and permission requirements, which keeps it off 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 purpose is front-loaded in one short sentence, followed by a clearly delineated caveat. Both parts earn their place; only the redundant restatement that the reference documents only GET could be trimmed.

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

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

An output schema exists, so return values need not be explained, and annotations cover the mutation profile. However, for a write tool with 0% parameter coverage, the description leaves gaps around the required name field and failure modes (duplicate role, permission denial) that an agent would need before calling it confidently.

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

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

Schema description coverage is 0% for the single required parameter "name", so the description is the only place semantics could be supplied. It says nothing about uniqueness constraints, length limits, or whether the name must be distinct from existing roles, leaving the sole parameter effectively undocumented.

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

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

"Create a new role" gives a specific verb and resource, and the name cleanly separates it from admin_list_roles / admin_update_role / admin_delete_role in the sibling list. It stops short of explicitly contrasting with those siblings, which is the only thing keeping it from a 5.

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

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

There is no statement of when to use this tool versus admin_list_roles or admin_update_role, nor any prerequisite (e.g., admin permission level) for creating a role. The only guidance is a stability warning about the underlying route, which is not usage guidance.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, non-idempotent, openWorld). The description adds genuinely new behavioral context: this tool calls an undocumented POST /tags route that Smartsheet may change or remove without notice. That warning materially affects an agent's risk calculus and is not in any structured field.

Agents need to know what a tool does to the 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 in one short sentence, followed by a compact warning. Slightly muddled because "Undocumented route" is not explicitly tied to "this tool uses it," but there is no wasted padding.

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

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

An output schema exists, so return values need not be explained, and the annotations cover safety. However, for a non-idempotent mutation on an unofficial endpoint, the description omits scope (global vs project vs user), duplicate handling, and permission requirements — enough gaps to leave an agent guessing.

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

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

Schema description coverage is 0% for the single required parameter, so the description bears the burden of explaining `name` and does not — no format, length, uniqueness, or scoping rules are given. It spends its words on route provenance rather than the one input the agent must supply.

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

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

"Create a tag" gives a clear verb+resource and is immediately actionable. It does not distinguish the tool from siblings like admin_list_tags or admin_delete_tag, nor does it clarify which tag namespace (project/user/global) is being created.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 call this instead of the documented routes it mentions, nor does it give prerequisites (existing project_id/user_id, duplicate-name behavior). The reader learns about alternatives only as an API-stability footnote, not as routing guidance.

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

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the create-and-write nature is covered. The description adds nothing beyond this – no mention of whether the email must be unique, whether an invitation/notification is sent, required role assignment, or what happens on duplicate creation.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably under-specified rather than appropriately sized for a 10-parameter mutation tool.

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

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

An output schema exists so return values need not be described, but with 10 parameters at 0% schema coverage and no usage or behavioral guidance, the definition is far too thin for a create tool that mutates an open-world system.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden of explaining them – and it names none. Non-obvious fields like user_type_id, billability_target, bill_rate, cost_rate, and discipline are left entirely unexplained.

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

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

The description states a specific verb and resource ('Create a new user profile'), which is clearly identifiable. However, it offers no differentiation from siblings like admin_update_user or admin_create_user_bill_rate, so the agent must rely on the name alone to route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 admin_update_user, admin_create_role, or any of the other admin_create_* siblings. No prerequisites, no exclusions, no context about what 'profile in Smartsheet RM' entails.

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

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

Beyond annotations, the description discloses that this is an undocumented route that may change or be removed without notice. That is valuable behavioral context for a mutation tool. It stops short of explaining duplicate handling, rate semantics, or permission requirements.

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

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

The purpose is front-loaded and zero-waste. The undocumented-route caveat is useful but somewhat repetitive in restating that the reference documents bill rates elsewhere without a create endpoint.

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

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

The tool is a create operation with no schema parameter descriptions and only sparse semantic detail in the description. Output schema exists, so return values need not be described, but key call-correctness details such as rate units and date format are missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only broadly implies user, rate, and effective date range. It does not clarify rate units, date formats, or user_id expectations.

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

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

The first sentence states a specific verb and resource: add a bill rate tier with an effective date range for a user. It is clearly distinguishable from the sibling list/get bill rate tools.

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

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

The description explains what the tool does but gives no explicit when-to-use guidance, prerequisites, or alternatives such as admin_list_user_bill_rates. The undocumented-route warning is risk context, not usage guidance.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent mutation with open-world effects, so the safety profile is covered. The description adds nothing beyond that: it doesn't say a POST is issued to callback_url, whether duplicate subscriptions are possible (idempotentHint=false), or that delivery is asynchronous/at-least-once.

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

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

One tight, front-loaded sentence with concrete examples and no filler. It is efficient, though it is arguably too sparse for a mutation tool rather than padded.

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

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

An output schema exists so return values needn't be described, but for an open-world webhook registration the description omits callback delivery semantics, duplicate handling, permission requirements, and whether event_type is an open string or a fixed enum. These gaps are material for correct invocation.

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

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

Schema description coverage is 0% for both required parameters. The examples ('time.entry.created', 'project.updated') give real value for the event_type string, but callback_url is left entirely unexplained and there is no indication whether the listed event types are the full set or a sample.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Register a webhook subscription', which clearly distinguishes it from admin_list_webhooks and admin_delete_webhook. The event-type examples reinforce what a subscription is, but the description never explicitly contrasts itself with those 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?

No guidance on when to register a webhook versus using the list/delete siblings, and no prerequisites such as admin scope or a reachable, publicly resolvable callback endpoint. The agent must infer all of this from the tool 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?

Annotations already flag this as destructive, open-world, and non-idempotent. The description adds valuable context beyond annotations by stating that confirm=True is required and warning that the DELETE route is undocumented and may change or be removed without notice.

Agents need to know what a tool does to the 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 action and safety requirement, followed by a concise and relevant undocumented-route warning. Every sentence adds useful information.

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

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

Output schema exists and annotations cover safety profile, so return values need not be explained. The description covers the key destructive confirmation requirement and route instability, though it omits some usage context such as what happens to related contacts.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains the confirm parameter's destructive-operation requirement, but it does not clarify client_id semantics or accepted formats beyond the schema's anyOf definition.

Input schemas describe structure but not intent. Descriptions should explain 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: delete a client record. This clearly distinguishes it from admin_get_client, admin_update_client, admin_list_clients, and sibling delete tools for contacts or leave types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one important usage prerequisite: confirm=True is required for this destructive operation. However, it does not explain when to delete a client versus using another tool or when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotent=false, so the description's "Destructive" label is partly redundant. However, it adds two things the annotations cannot convey: the confirm=True gate, and the warning that this route is undocumented and may be changed or removed without notice. It still omits concrete behavior such as what happens if confirm is omitted (error vs. no-op) or whether the delete is permanent.

Agents need to know what a tool does to the 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 precondition is front-loaded in the first sentence and the caveat follows. The undocumented-route paragraph is longer than strictly necessary and could be compressed to one clause, but it carries non-obvious risk information.

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

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

An output schema exists, so return values need not be explained, and the risk caveat is a genuine addition. For a destructive mutation with zero schema description coverage and no annotation-driven permission info, the description should still say what happens without confirm and whether removal is irreversible or affects the parent client.

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

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

Schema description coverage is 0%, so the description must compensate. It covers the most dangerous parameter (confirm=True) and the route template makes the meaning of client_id and contact_id clear, but it never explains the accepted id variants (integer or string) or the default-false behavior of confirm. That is partial compensation, not full.

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

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

States a specific verb and resource ("Delete a client contact") and the route template `DELETE /clients/{id}/contacts/{contact_id}` removes any ambiguity about which object is removed versus the sibling admin_delete_client. It does not explicitly name the sibling alternatives (admin_delete_client, admin_update_client_contact) to route an agent, 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 only usage guidance is the inline precondition "requires confirm=True", which is valuable, but there is no statement of when to choose this over admin_delete_client or admin_update_client_contact, nor when deletion is inappropriate. Usage is inferable from the resource name alone, which is the definition of a 3.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral information the annotations do not carry: the call requires confirm=True. It still omits downstream effects (e.g., whether stored values are destroyed) and any permission requirements.

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

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

A single sentence that front-loads the action and appends the critical precondition in parentheses. Nothing is redundant and nothing is buried.

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

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

An output schema exists so return values need no explanation, and annotations cover the destructive profile. However, with zero schema description coverage the description should say more about what deletion entails and what the call requires, and it does not fully close that gap for a permanent, non-idempotent mutation.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only partially does: it documents the confirm gate and the value it must take. The custom_field_id parameter, including its int-or-string anyOf shape, is left entirely undocumented.

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

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

States a specific verb and resource ('Delete a custom field definition'), which implicitly separates it from sibling operations like admin_set_custom_field_values and admin_update_custom_field. It does not explicitly name a sibling or contrast scope, so it stops short of a 5.

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

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

There is no guidance on when to delete a definition versus updating it or clearing values, nor any prerequisites beyond the inline confirm flag. The agent must infer the usage context entirely from the tool name and the deletion semantics.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds meaningful context: the operation is destructive, requires confirmation, and uses an undocumented route that may change or be removed. It does not explain downstream effects of deleting a discipline, but the key risk information is 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 description is two sentences with no wasted language. The destructive confirmation requirement is front-loaded, followed by the important undocumented-route caveat.

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

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

The warning about the undocumented route and the confirm requirement cover the main behavioral risks. However, with 0% schema description coverage, the missing explanation of discipline_id leaves an important input-semantics gap.

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

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

Schema description coverage is 0%, so the description needs to explain both parameters. It clarifies that confirm must be set to True, which is useful beyond the schema default, but it says nothing about the required discipline_id parameter or its accepted integer/string format.

Input schemas describe structure but not intent. Descriptions should explain 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: deleting a discipline. This clearly distinguishes it from sibling operations such as admin_create_discipline, admin_update_discipline, and admin_list_disciplines.

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

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

It gives a concrete usage prerequisite: confirm=True is required. However, it does not explicitly state when not to use it or name alternatives, which keeps it below the top score.

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

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

Beyond the destructiveHint annotation, the description adds the confirm=True requirement and warns that the DELETE /expenses/{id} route is undocumented and may change or be removed. This is exactly the kind of behavioral and operational context annotations do not provide.

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

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

The main action and destructive confirmation requirement are front-loaded, and the route warning follows with useful context. There is no wasted text.

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

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

The description covers the key deletion behavior, confirmation requirement, and route risk, and an output schema exists. It could be more complete by noting permission requirements or whether related data is affected, but it is sufficient for this two-parameter destructive tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains confirm=True and implies expense_id via the route placeholders, but it does not clarify the anyOf integer/string nature of expense_id or other identifier semantics.

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

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

The description states a specific verb and resource: "Delete an expense item." It also distinguishes the operation as destructive and names the concrete API routes, so an agent can identify the tool without ambiguity against sibling expense tools.

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

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

It gives a clear usage condition: deletion requires confirm=True. It does not explicitly compare against alternatives such as admin_delete_expense_category, but the deletion scope is clear enough for correct tool selection.

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

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

Annotations already declare destructiveHint=true and non-idempotency, but the description adds two things they do not: the confirm=True gate and the warning that DELETE /expense_categories/{id} is undocumented and may be removed without notice. That undocumented-route disclosure is exactly the kind of beyond-annotation context this dimension rewards; it lacks only a statement on reversibility or what happens to dependent expense records.

Agents need to know what a tool does to the 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 action and confirm requirement are front-loaded in the first line, with the API-stability caveat following. The caveat is slightly verbose but every clause is substantive; 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers the confirm gate and route instability, missing only the side effects on existing expense records and whether deletion is permanent — a modest but real gap for a destructive admin 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 0%, so the description must carry parameter meaning. It explains confirm's required value and purpose well, but says nothing about category_id beyond its presence — notably whether it accepts an integer ID or a string identifier and how to obtain one, leaving half the undocumented surface unexplained.

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

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

The first sentence names a specific verb (Delete) and resource (expense category), which is enough to separate it from admin_list_expense_categories and admin_create_expense_category in the sibling set. It stops short of describing scope, e.g. whether deletion cascades to expenses already filed under the category.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 confirm=True prerequisite is stated, which is real invocation guidance, but there is no explicit when-to-use/when-not or reference to an alternative such as reassigning expenses first. Usage context is implied by the name and the destructive label rather than spelled out.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding the confirm gate and the important warning that the underlying DELETE route is undocumented and may change or be removed without notice. It stops short of describing blast radius (e.g., whether existing time entries referencing the holiday are affected) or required permissions.

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

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

Two sentences, front-loaded with the action and the destructive/confirm requirement, followed by the endpoint-stability caveat. The route-documentation aside is longer than strictly necessary but carries genuine risk information.

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

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

For a two-parameter destructive mutation with full annotation coverage and an output schema, the description covers the safety gate and endpoint fragility. Remaining gaps — irreversibility statement, permission requirements, and effect on related time data — are minor but real.

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

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

Schema description coverage is 0%, so the description must compensate: it explains that the 'confirm' flag must be set to True, which the schema only shows as a boolean defaulting to false. 'holiday_id' is left implicit, but its name and the tool's purpose make its meaning evident.

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

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

States a specific verb and resource ('Delete a holiday') that is unambiguous against the many sibling admin_* tools, since no other sibling destroys holidays. It does not explicitly name the nearest alternatives (admin_delete_leave_type, admin_update_holiday), so it stops short of full sibling differentiation.

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

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

Gives a concrete precondition ('requires confirm=True'), which is the key operational guidance an agent needs before calling. It doesn't state when to use deletion versus updating/deactivating, or what to do if the holiday id is unknown (admin_get_holiday / admin_list_holidays), so context is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered; the description goes beyond them by disclosing that the DELETE route is undocumented and may change or be removed without notice — a genuinely useful risk signal. It does not say what happens to existing records referencing the leave type, which keeps 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?

Two sentences, with the destructive confirmation requirement front-loaded where an agent will see it. The second sentence is long but the undocumented-route warning earns its space.

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

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

An output schema exists, so return values need no explanation, and the confirmation gate plus API-stability warning are covered. What is missing for a destructive admin tool is the blast radius: whether deletion cascades to assignments or time entries, and whether the operation is reversible.

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

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

Schema description coverage is 0%, so the description must carry the load: it explains that confirm=True is required to actually delete (schema only shows a default of false, without stating the consequence of omitting it). However, leave_type_id's anyOf integer-or-string format and the behavior when confirm is false/absent are left undocumented.

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

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

States a specific verb and resource ("Delete a leave type") and distinguishes it from the create/get/update leave-type siblings by naming the destructive action explicitly. The confirm gate is front-loaded so the agent immediately knows what class of operation this is.

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

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

The description gives a prerequisite (confirm=True) but never says when to choose this over alternatives — e.g., whether admin_update_leave_type can deactivate instead, or what to do if the leave type is in use. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds material context: the confirm gate and the warning that this route is undocumented and may be removed by the provider. It does not say what happens to dependent users/assignments, 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?

Three short sentences, front-loaded with the operation and safety gate, then the API stability caveat. Nothing is padded; each sentence adds a fact an agent needs.

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

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

With an output schema present, return values need no explanation, and the confirm requirement plus the undocumented-route warning cover the main risks of a destructive admin call. Missing only cascade/impact information about roles in use.

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

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

Schema description coverage is 0%, so the description has to carry the load; it documents 'confirm' only implicitly ('requires confirm=True') without stating the default false or consequence of leaving it off. The role_id anyOf integer/string flexibility is undocumented in both places.

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

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

States a specific verb and resource ('Delete a role') with the destructive caveat inline, which cleanly separates it from admin_update_role, admin_create_role, and the list/get siblings. 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?

The mandatory confirm=True is a usage prerequisite explicitly stated, which is valuable. But there is no guidance on when deletion is appropriate vs admin_update_role, or on what happens to users currently assigned the role.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds two things they do not: the mandatory confirm=True gate and a warning that the underlying route is undocumented and may change without notice. It does not describe the effect of deletion on items already carrying the tag, which would be the remaining high-value disclosure.

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

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

Two sentences, front-loaded with the action and the destructive/confirm warning. The route-list sentence is dense but carries genuine volatility information rather than 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies the confirm gate and route-stability caveat, though it omits what happens to tag associations after deletion and what error surfaces if confirm is false.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the confirm semantics ('requires confirm=True') but says nothing about tag_id, whose anyOf integer-or-string type is left ambiguous to the caller.

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

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

States a specific verb and resource ('Delete a tag'), which is immediately distinguishable from the sibling list/create tag tools by operation type. It does not explicitly name the siblings it differs from, so it stops short of the top mark.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 concrete usage prerequisite ('requires confirm=True') and names the two documented alternative routes (project-scoped and user-scoped tag deletion). It does not say when to prefer those documented routes over this one, so the selection criteria remain implicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description usefully adds the confirm=True requirement, which is not visible in the schema defaults, but it never clarifies whether the outcome is permanent deletion or a recoverable archive.

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

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

A single sentence with no filler, and the destructive nature plus the confirm precondition are front-loaded. The concision is slightly bought at the cost of the delete-vs-archive ambiguity.

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

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

An output schema exists, so return values need not be described. For a destructive, non-idempotent mutation the critical confirm gate is covered, but the unresolved delete/archive distinction and the undocumented user_id formats leave 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 coverage is 0%, so the description must carry the burden: it does explain the non-obvious confirm=True requirement, which matches the parameter's default of false. It says nothing about user_id's accepted forms (integer or string), leaving half the parameters unexplained.

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

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

States a specific verb and resource ("Delete or archive a user") that clearly distinguishes it from siblings like admin_list_users, admin_get_user, and admin_update_user. The "or archive" wording leaves some ambiguity about which operation actually occurs, which keeps it 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?

It signals a destructive operation and names the required confirm=True gate, which is a usage precondition. It does not say when to choose delete/archive over an alternative such as admin_update_user for deactivation, so routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the operation is gated on confirm=True. It stops short of saying what happens if confirm is omitted or false (the schema default is false), leaving the failure mode unspecified.

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

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

A single front-loaded sentence with no filler. The destructive warning and confirm gate are placed immediately after the action, where an agent will see them.

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

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

An output schema exists, so return values need not be described. For a destructive mutation the description covers the essential confirm requirement, but omits the consequence of omitting confirm, whether deletion is permanent, and any auth/permission expectations — gaps that matter for a destructive admin 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 0%, so the description must compensate. It explains the confirm parameter's required value, which is real added meaning, but says nothing about webhook_id (its int-or-string form, where to obtain it, or whether it is reusable after deletion). Partial compensation warrants the baseline-ish 3.

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

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

States a specific verb+resource ('Delete a webhook subscription') that is unambiguous and clearly separable from the sibling admin_create_webhook and admin_list_webhooks. It does not explicitly route against those siblings, but the action plus resource name is enough for an agent to tell them apart.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as admin_list_webhooks for identifying the target webhook_id first. The parenthetical only restates the destructive nature already implied by 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful context annotations cannot express: the route is undocumented and may be changed or removed without notice. It stops short of saying what happens on an unknown client_id or what the payload contains.

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

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

Two short sentences, front-loaded with purpose followed by the risk caveat. Slightly verbose in citing two documentation sources, but no sentence is wasted.

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

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

A read-only single-record fetch with an output schema and full annotation coverage needs little more than purpose plus any volatility caveat. The description delivers exactly that, and the return shape is handled by the output schema.

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

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

Only one parameter, but schema description coverage is 0% and client_id accepts either an integer or a string. The description adds nothing about which form to pass or where the value comes from, leaving the union type unexplained, though the param name is largely self-evident.

Input schemas describe structure but not intent. Descriptions should explain 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 (client) with clarifying scope ('a specific client'), which distinguishes it from admin_list_clients. It does not explicitly name the sibling it pairs with, so the 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?

No guidance on when to call this versus admin_list_clients (to discover an id) or admin_get_user-style patterns. The only conditional text is a stability warning, not usage routing; the agent must infer that client_id comes from admin_list_clients.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds nothing beyond the purpose sentence - no note on which definition types are supported, whether inactive/deleted fields are returned, or any auth/scope requirement.

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

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

A single front-loaded sentence with zero filler. It is efficient, though at this length it is arguably under-specified rather than optimally concise.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains missing is context the structured fields cannot supply: the distinction between a custom field definition and custom field values, and the expected identifier format.

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

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

One required parameter with 0% schema description coverage: custom_field_id is typed only as anyOf integer|string with no explanation. The description does not clarify what form of identifier is expected (numeric ID vs. string key) or where to obtain it, so it fails to compensate for the coverage gap.

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

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

States a specific verb (Get) and resource (details of a custom field definition), which clearly marks it as a single-item lookup as opposed to the sibling admin_list_custom_fields. It stops short of explicitly naming or distinguishing itself from siblings, but the singular 'definition' does the disambiguating work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisite (e.g. where a custom_field_id comes from), and no mention of alternatives such as admin_list_custom_fields or admin_list_custom_field_values. The agent must infer usage 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?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: this route is undocumented and may be changed or removed without notice, plus it names the two documented equivalent routes. It stops short of describing response shape, though an 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?

Two sentences with the purpose front-loaded and the caveat second. The route-stability warning is dense but earns its place given the API risk; nothing else is wasted.

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

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

With an output schema present, return values need not be explained, and the safety/risk profile is fully covered by annotations plus the undocumented-route warning. The remaining gap is what the ID actually refers to, which matters for correct invocation.

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

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

Schema description coverage is 0%, so the single parameter expense_id is undocumented in structured data. The description never clarifies whether this is a numeric expense-item ID or a string identifier, nor why the schema accepts both integer and string — the `{id}` in the route text is only a weak hint.

Input schemas describe structure but not intent. Descriptions should explain 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 details for a specific logged expense"), which clearly separates it from list/create/update/delete siblings in the admin_expense family. It does not explicitly name the closest alternative (admin_list_expenses) or state that it returns a single record by ID, but the singular-object framing makes that inferable.

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

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

No guidance on when to choose this over admin_list_expenses or admin_get_expense_categories, and no preconditions (permissions, whether the expense must be in a specific state). The description spends its only contextual sentences on API route provenance rather than on 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?

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds important non-annotation context: the endpoint is undocumented, absent from official references, and may change or be removed without notice.

Agents need to know what a tool does to the 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 a short first sentence, and the warning sentence is relevant. The second sentence is somewhat dense and repeats the reference-documentation point, but it earns its place by flagging endpoint instability.

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

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

The tool is simple, annotations cover safety, and an output schema exists, so the description does not need to explain return values. However, it omits practical guidance on obtaining the holiday ID and clarifying parameter format, leaving some gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented holiday_id parameter. It only implies that the ID maps to /holidays/{id}; it does not explain accepted formats, the integer-or-string flexibility, or where to obtain the ID.

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

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

The first sentence states a specific verb and resource: getting details for a specific holiday. It clearly implies retrieval by ID rather than listing, but it does not explicitly name or contrast with sibling tools such as admin_list_holidays.

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

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

The description explains what the tool does but gives no guidance on when to use it versus alternatives. It does not say to obtain an ID from admin_list_holidays or clarify when a specific-holiday lookup is preferable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered elsewhere. The description adds nothing on top of that - no note on lookup behavior, error/not-found semantics, or auth requirements - so it contributes no incremental behavioral context.

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

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

A single short sentence with no wasted words, but its brevity comes from under-specification rather than disciplined compression. It is appropriately sized for a simple lookup but earns little.

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

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

An output schema exists, so return values need not be explained, but the description still omits the identifier format for its one required parameter and any distinction from the sibling list/create/update/delete leave-type tools. For a lookup tool it is minimally adequate but leaves real 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 0% and the single parameter leave_type_id is an anyOf of integer or string with no documentation in either place. The description does not clarify the accepted identifier format or which form callers should pass, leaving the only required input under-specified.

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

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

It states a verb (Get) and a resource (leave type) scoped to one item, which distinguishes it from the list variant by implication. However, "details" is vague and the sentence largely restates the name and title rather than saying what is actually returned.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative admin_list_leave_types. The agent must infer that this is the by-ID lookup versus the collection listing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds nothing beyond that – notably it doesn't explain the opaque report_parameters blob, whether results are paginated, or how the open-world report schema is interpreted.

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

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

A single short sentence that is front-loaded and wastes no words, but its brevity stems from under-specification rather than disciplined concision. There is room for another clause about report parameters without bloat.

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

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

An output schema exists, so return values need not be described. However, the one input is an entirely undocumented nested object and the relationship to the sibling admin_get_report_totals is unstated, leaving the agent without enough to call this correctly.

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

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

The single required parameter is a free-form object with additionalProperties:true and 0% schema description coverage, so the schema conveys zero semantics. The description must compensate and does not – the structure, keys, or expected report identifiers of report_parameters are never hinted at.

Input schemas describe structure but not intent. Descriptions should explain 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 largely restates the tool name: 'Generate detailed custom report rows' vs. 'Admin Get Report Rows'. The only added words ('detailed', 'custom') don't tell an agent what distinguishes this from the sibling admin_get_report_totals or what a 'row' contains.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 versus admin_get_report_totals, which is the obvious alternative for report data. No prerequisites, no mention of whether rows and totals are meant to be called together or what report types are supported.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds almost nothing beyond that — no indication of auth requirements, scope of the aggregation, or cost/latency. The word 'Generate' could read as a mutation if the annotations weren't present, but it doesn't directly contradict them.

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

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

One short, front-loaded sentence with no filler, so it is concise. But the brevity comes at the cost of substance rather than being tight-but-complete.

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

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

An output schema exists, so return values need no explanation. But for a tool whose only input is an untyped, undocumented nested object, the description should at minimum describe the shape of report_parameters; it leaves the agent unable to form a valid request.

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

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

The single required parameter 'report_parameters' is a free-form nested object with additionalProperties=true and 0% schema description coverage. The description provides no hint about which keys are accepted, so the agent has essentially nothing to construct a valid call.

Input schemas describe structure but not intent. Descriptions should explain 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 verb (Generate) and a resource (aggregated custom report totals), and the 'totals' vs 'rows' wording loosely distinguishes it from the sibling admin_get_report_rows. However, 'custom report' is never defined and the scope of the aggregation is left vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 versus admin_get_report_rows or the many admin_list_* tools. The agent must infer that 'totals' means summarized output rather than row-level data, with no explicit conditions or exclusions given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds nothing beyond that: it doesn't say what detail set is returned, whether admin privileges are required (the 'admin_' prefix implies it), or what happens for an unknown user_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?

One short, front-loaded sentence with zero padding or redundancy. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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

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

An output schema exists, so return values needn't be explained, and the operation is simple (one parameter). However, with a polymorphic user_id and no sibling differentiation in a namespace containing several near-identical 'get user'-style tools, the description is thinner than an agent would like.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single user_id parameter and simply doesn't address it. The schema allows either an integer or a string, and the description gives no hint about which form is expected or whether the two are interchangeable.

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

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

The description pairs a clear verb ('Get') with a specific resource ('details for a specific user'), so the core purpose is unambiguous. It offers no differentiation from the many closely-related siblings (admin_list_users, admin_get_user_availability, admin_get_user_utilization), which is the only thing keeping it from a 5.

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

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

There is no indication of when to use this tool versus admin_list_users or the user availability/utilization getters. No prerequisites, no exclusions, no alternative named. The agent must infer all routing from the tool 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?

The description adds important behavioral context beyond annotations: it warns that the route is undocumented and may be changed or removed without notice, which is a critical stability concern. Annotations already cover read-only and idempotent traits, so this warning is valuable added information.

Agents need to know what a tool does to the 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 core purpose in the first sentence, followed by a concise warning about the undocumented route. It is appropriately sized for the tool's complexity, though the route documentation could be slightly more compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema exists and annotations cover safety, the description provides the essential purpose and stability warning. However, it lacks parameter semantics and usage guidance, leaving gaps for an agent trying to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it only indirectly references user_id via the route string and does not explain the meaning, format, or usage of from_date and to_date. The parameter names are somewhat self-explanatory, but the description adds no semantic 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?

The description clearly states the tool's function with a specific verb and resource: 'Query scheduled hours vs available capacity for a user.' It distinguishes the tool from generic admin or time tools by focusing on availability, but it does not explicitly differentiate from similar siblings like admin_get_user_utilization or admin_get_user_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?

The description provides no guidance on when to use this tool versus alternatives. It mentions route documentation but does not specify appropriate scenarios, prerequisites, or exclusions for querying user availability.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds only the domain vocabulary of status codes (ITO, WFH, SIC, OOO, VAC, OOF), saying nothing about auth scope, result volume, pagination, or time-range limits.

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

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

A single compact sentence that front-loads the action and resource, with the status-code enumeration tucked in parenthetically. Nothing is wasted, though the brevity comes at the cost of missing context.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a user-scoped admin read tool the description omits parameter format, permission requirements, and any temporal scoping, leaving 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?

With one required parameter and 0% schema description coverage, the description carries the full burden, but 'a specific user' only restates the obvious. It never clarifies whether user_id is a numeric ID, email, or username, despite the schema accepting both integer and string.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Retrieve work status history for a specific user'), which is clearly distinct from the setter sibling admin_set_user_status and from admin_get_user. It does not explicitly name or differentiate itself from any sibling, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as admin_get_user or admin_get_user_availability, and no stated prerequisites (e.g., admin privileges). Usage is only inferable 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: the endpoint is undocumented and may be changed or removed without notice, which an agent should factor into reliance decisions. It omits behavior around date-range filtering and result shape, keeping it off a 5.

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

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

Two sentences, zero waste, with the purpose front-loaded and the volatility caveat immediately after. Nothing repeats the schema or annotations.

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

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

Output schema exists, so return values need not be explained, and annotations cover safety. However, for a metric tool with an untyped date range and no parameter documentation, the description leaves an agent guessing about the accepted date format and the effective default window.

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

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

Schema description coverage is 0% for all three parameters, and the description says nothing about user_id, from_date, or to_date. The date parameters are bare strings with no format stated anywhere, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Get billable utilization metrics for a user', which is concrete enough to distinguish it from generic user lookups. It does not explicitly differentiate itself from nearby siblings like admin_get_user_availability or admin_get_user_bill_rates, so it falls short of a 5.

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

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

No statement of when to use this versus admin_get_user_availability, admin_get_user_bill_rates, or the time_* reporting tools. The only guidance-like content is a stability warning about the undocumented route, which is a risk note rather than usage routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description earns credit by adding information the annotations cannot convey: the underlying route is undocumented, absent from both the current and archived API references, and may be changed or removed without notice — a real operational risk an agent should weigh. It stops short of describing pagination, ordering, or result 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?

Purpose is front-loaded in the first sentence and the caveat follows, so an agent gets the gist immediately. The second sentence is slightly repetitive (naming two source documents and restating 'no documented equivalent'), but every claim it makes is decision-relevant, so little is wasted.

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

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

For a single-parameter read tool with full annotation coverage and an output schema (so return shape needn't be explained), the description covers purpose and the stability caveat adequately. The remaining gap is the identifier semantics and any paging/filtering behavior, which matter given the 0% schema coverage on the one required parameter.

Complex tools with many parameters or behaviors need more documentation. 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 description coverage is 0%, so the schema supplies no semantics for client_id beyond a bare anyOf integer|string. The description partially compensates by establishing that the identifier scopes to a client whose contacts are returned, but it never states whether the integer is an internal ID or the string is a name/external key, which is exactly the ambiguity the anyOf creates.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List contacts associated with a client'), which is unambiguous about what the call returns. It implicitly distinguishes itself from the sibling mutation tools (admin_create_client_contact, admin_update_client_contact, admin_delete_client_contact) by being the read/list variant, though it never names them explicitly.

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

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

Usage is only implicit: the phrasing 'associated with a client' signals that a client scope is required and nothing else is described. There is no statement of when to prefer this over a general contact lookup or over fetching the client itself via admin_get_client, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new context that the route is undocumented and may be changed or removed without notice, which is a real stability risk an agent should know. It stops short of describing result ordering or pagination behavior.

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

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

Two short sentences, front-loaded with the action and followed by the risk caveat; little waste. The closing "No documented equivalent was found" is arguably filler but is brief enough not to hurt.

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

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

An output schema exists so return values need not be spelled out, and annotations carry the safety profile. However, for a paginated list tool the description never mentions pagination or the archived filter, leaving the agent without enough to call it correctly beyond defaults.

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

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

Three parameters (page, archived, per_page) have 0% schema description coverage, and the description supplies no meaning for any of them — notably the archived tri-state null/true/false filter and the default page size are left entirely unexplained. With coverage this low the description was required to compensate and does not.

Input schemas describe structure but not intent. Descriptions should explain 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 clients" states a verb and resource, but there are 40+ sibling admin tools including admin_get_client, admin_list_client_contacts and admin_list_clients-adjacent lists, and the description does nothing to distinguish this one from them. The second paragraph is about API provenance, not about what the tool returns or how it differs from its 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?

There is no statement of when to use this list endpoint versus admin_get_client for a single record, nor when to include archived clients. The only routing-adjacent sentence — "No documented equivalent was found" — tells the agent nothing about selecting this tool over an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context such as pagination, filtering, or output format; it merely restates the 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?

A single, front-loaded sentence with no filler. It communicates the operation immediately and every word earns its place.

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

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

For a no-parameter list tool with rich annotations and an output schema, the description is nearly sufficient. It does not need to explain return values, but it also offers no additional scope such as 'all definitions' or pagination behavior that would make it fully self-contained.

Complex tools with many parameters or behaviors need more documentation. 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 are no parameters, so the baseline is 4 per the rubric. Schema coverage is 100% (empty schema), and the description does not need to compensate for any parameter meaning.

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

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

States a specific verb ('List') and resource ('custom field definitions'), which distinguishes it from siblings like admin_list_custom_field_values and admin_get_custom_field. However, it does not explicitly name an alternative or scope, so it lacks the explicit sibling-differentiation of a 5.

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

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

Provides no when-to-use guidance, prerequisites, or alternative tools. The agent can infer it is for reading definitions, but the description offers no selection criteria among the many admin_list_* siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds genuinely non-obvious context: the underlying GET /custom_field_values route is undocumented and may change or be removed without notice, and it points to the documented per-project/per-user routes. That is exactly the kind of risk disclosure an agent cannot get from structured fields.

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

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

Two sentences, front-loaded with the action and filter semantics, followed by the risk caveat. The route-path citations are somewhat verbose but each carries informational weight about stability.

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

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

A read-only, zero-required-parameter list tool with an output schema and full annotation coverage needs little more than what is here; the description covers the resource, the filter behavior, and the undocumented-endpoint risk. Nothing essential for a correct call is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description only restates that the two parameters act together as an entity filter, adding no format or pairing rules beyond what the schema already says ('use with target_type').

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

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

States a specific verb and resource ('List custom field values') plus the optional scoping by target_id and target_type. It is clearly distinguishable from the write-side sibling admin_set_custom_field_values and from admin_list_custom_fields (field definitions vs. values), though it never names those siblings 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 'optionally filtered to one entity by target_id and target_type' implies when the filters apply, but there is no explicit statement of when to prefer this tool over admin_list_custom_fields or admin_set_custom_field_values, nor any exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the word 'all', which hints at unfiltered/unpaginated output but stops short of confirming it, so it contributes modest extra context.

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

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

A single six-word sentence with the verb and resource front-loaded and zero filler. Nothing could be trimmed without losing meaning.

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

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

With zero parameters and an output schema present, the description need not explain return values, and annotations carry the safety profile, so the definition is nearly complete. It could still note that results are unfiltered and unpaginated (relevant for a workspace with many disciplines) to fully close the loop.

Complex tools with many parameters or behaviors need more documentation. 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 for the description to explain; the baseline for a 0-param tool applies. Nothing in the description misleads 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 ('List') and resource ('disciplines'), making it immediately distinguishable from sibling mutations like admin_create_discipline and admin_delete_discipline. It does not explicitly contrast itself with those siblings, but the naming pattern makes the read intent 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?

Usage is only implied: an agent can infer this is the read path used to discover disciplines before creating, updating, or deleting one. There is no explicit when-to-use statement, no mention of whether the result feeds admin_create_discipline, 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the bar is lower. The description adds genuinely new behavioral context: the endpoint is undocumented so Smartsheet may change or remove it without notice, and it names the documented equivalent route — a real risk disclosure an agent couldn't get from structured fields.

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

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

Two short sentences, front-loaded with the purpose, followed by the caveat. Minimal waste, though the route strings are slightly technical for a purely descriptive line.

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

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

Output schema exists so return values needn't be described; annotations cover safety. For a zero-param read tool the description is nearly complete, with only minor gaps like whether inactive categories are included.

Complex tools with many parameters or behaviors need more documentation. 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 (schema coverage 100% by default), so there is no parameter semantics to explain. Baseline 4 applies for a no-arg tool.

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

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

The description states a specific verb+resource ('List configured expense categories'), which is unambiguous. It doesn't need to differentiate from a sibling because no other expense-category-list tool exists, though it could have named related siblings like admin_create_expense_category or admin_list_expenses.

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

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

There is no guidance on when to use this tool versus alternatives, nor prerequisites. The route note describes provenance and stability, not usage context, so the agent is left to infer conditions from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations by warning that several routes are undocumented and may change or be removed without notice, while identifying the documented routes.

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

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

The purpose is front-loaded and the warning about undocumented routes follows immediately. The text is information-dense without wasted sentences, though the route-level API detail is somewhat technical for a tool description.

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

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

The definition covers purpose, filter scope, and route stability, and an output schema exists so return values need not be explained. However, for a six-parameter list tool with 0% schema coverage, the absence of date-range and pagination semantics leaves a meaningful completeness gap.

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

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

Schema description coverage is 0%, so the description must compensate for six undocumented parameters. It only indirectly explains project_id and user_id filtering; from_date, to_date, page, and per_page are not described, leaving most parameters without semantic guidance.

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

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

The description clearly states the verb and resource: it lists logged expenses and describes the scope as across projects or filtered by project/user. It is specific enough to distinguish listing from the singular get/create/update/delete expense siblings, though it does not explicitly name those alternatives.

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

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

The description implies usage by explaining that expenses can be listed across projects or filtered by project/user. However, it gives no explicit when-to-use guidance versus admin_get_expense, admin_list_expense_categories, or other admin list tools, and it does not mention prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only the fact that both company and regional holidays are returned, which is modest added context beyond the annotations.

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

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

A single short sentence with zero filler and the resource front-loaded. It is efficient, though the brevity edges into under-specification rather than pure conciseness.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety semantics. The gap is the undocumented date-range parameters and lack of any routing versus admin_get_holiday, making the definition minimally viable rather than complete.

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