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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description usefully adds the auth mechanism (User API key via api-access-token header) and an encoding caveat about Persian/Arabic-Indic digits, but says nothing about return format, time-range scoping, or rate limits.

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

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

The definition is short and front-loads the purpose, followed by endpoint, auth, and i18n notes. The mixed format (prose + endpoint + auth lines) is slightly disjointed but every line carries information.

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

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

With no output schema, the description is the only place to learn what the metrics contain, yet it never characterizes the returned data or any time-range filtering. For a metrics/report endpoint that is a meaningful gap, though the auth and encoding notes partially compensate.

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

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

Schema description coverage is 100%, with account_id and the type query param already documented in the schema. The description adds no syntax or format detail for either parameter, so the baseline of 3 applies.

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

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

The description states a clear verb and resource: 'Get conversation metrics for Account'. This is specific enough to distinguish it from the account/agent report siblings, though it does not name gapify_agent_conversation_metrics or gapify_get_account_reports to make the boundary explicit.

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

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

There is no guidance on when to use this tool versus the closely-related gapify_agent_conversation_metrics, gapify_get_account_reports, or gapify_get_account_reports_summary. The agent must infer the selection from names alone.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world behavior, so the bar is lower; the description still adds real context: the auth requirement (User API key in the api-access-token header), the required body fields, and the extra_body escape hatch for unlisted keys. It omits failure modes such as duplicate-email handling, 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?

Front-loaded with the action, then endpoint, auth, body fields, and the encoding note — each line carries distinct information with no filler. It is slightly list-like but every element 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 7-parameter creation tool with no output schema, the description covers auth, required vs optional fields, the extra_body mechanism, and encoding quirks, which is close to sufficient. Remaining gaps are behavioral edge cases (duplicate email, validation errors) rather than anything needed to construct a correct call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes beyond the schema by calling out which fields are required in prose, explaining extra_body's merge semantics for keys not listed in the schema, and noting that Persian/Arabic-Indic digits and non-Latin text are passed through unchanged. The digit/language note is genuinely information the schema does not carry.

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 new agent to the account') and pins it to the underlying endpoint, so the agent knows exactly what is created. It does not, however, differentiate itself from nearby siblings such as gapify_create_agent_bot or gapify_platform_create_account_user, which a reader must infer from naming alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The closest thing to routing help is the [Agents] tag and endpoint path, which only weakly separates this from the agent-bot and account-user creation tools in the sibling list.

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

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

Annotations already declare the write/non-idempotent/open-world/non-destructive profile, and the description adds real context beyond them: the exact endpoint, the auth mechanism ('User API key' via api-access-token header), and the extra_body escape hatch for unlisted fields. It still omits failure/error behavior and any response expectations.

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?

Well front-loaded: purpose first, then endpoint, auth, and field notes. The enumerated body-field list largely duplicates the schema and adds length without information, which keeps it from a 5.

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

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

For a 14-parameter create tool with no output schema, the description supplies the endpoint, auth, external-field escape hatch, and value-encoding rules, which is fairly complete. It stops short of describing the returned article object or error cases, leaving minor gaps for an agent verifying success.

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

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

Schema description coverage is 100%, so the baseline is 3, and the field list here largely restates the schema. However, the note that text may be sent in Persian and that IDs/numbers may use Persian or Arabic-Indic digits is genuine value-add guidance about how to format parameter values that the schema does not provide.

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

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

The description states a specific verb and resource ('Add an article to a help center portal') and pins it with the exact endpoint path. This clearly separates it from the neighboring help-center creation tools like gapify_add_portal and gapify_add_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?

Usage is implied by the create semantics and the required account_id/portal_id, but there is no explicit when-to-use statement or routing against alternatives. Since there is no update/delete article sibling, the ambiguity is low, so this is merely adequate rather than strong.

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

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

Annotations declare a non-read-only, non-idempotent, open-world write, and the description adds genuinely new context: the exact auth header (`api-access-token`), the endpoint, the fact that extra fields can be merged via extra_body, and that Persian/Arabic-Indic digits and multilingual text are passed through unchanged. It does not cover failure modes, required-vs-optional fields, or what is returned, which keeps 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?

Front-loaded with the action, then a compact reference block (method/path, auth, body fields, encoding note). Every line carries information, though the bare 'POST /api/...' and 'Auth:' lines are terse reference fragments rather than prose and add some visual noise.

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

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

For an 8-parameter, nested-object write with no output schema, the description covers the endpoint, auth, all body fields, the extra_body escape hatch, and input encoding. It stops short of clarifying which of name/event_name/actions are effectively required at runtime or what a successful response contains, which the absent output schema leaves unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the body-field roster maps to the parameters, extra_body is explained as a merge channel for unlisted keys, and the note about Persian/Arabic-Indic digit handling is a non-obvious input contract absent from the schema.

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

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

States a specific verb and resource ('Add a new automation rule to account'), and the endpoint path plus bracketed resource tag reinforce that this is a creation operation on the automation_rules collection. Against siblings like gapify_list_automation_rules, gapify_get_automation_rule, gapify_update_automation_rule and gapify_remove_automation_rule, the create action 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?

Usage is implied by the verb and endpoint, and the auth line tells the agent a User API key is required, but there is no explicit when-to-use/when-not-to-use guidance or comparison to siblings such as gapify_update_automation_rule. An agent can infer the context but must supply the routing logic itself.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds valuable context beyond these: it specifies the required auth header (`api-access-token`), the exact endpoint path, that extra_body can merge additional fields, and that text/numbers may use Persian or Arabic-Indic scripts. This is meaningful behavioral disclosure for a write operation.

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

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

The description is front-loaded with the purpose, then structured into endpoint, auth, body fields, and a language note. Each line serves a purpose without excessive verbosity. It is appropriately sized for a create tool, though the multi-line format is slightly less concise than a single flowing sentence.

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

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

For a non-destructive write tool with full schema coverage and clear annotations, the description is largely complete. It covers auth, endpoint, body fields, and input script handling. It omits any mention of success response shape or error behavior, but with no output schema and annotations covering the safety profile, these omissions are minor.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by naming the body fields (content, short_code), explaining extra_body merging, and adding a non-obvious semantic detail: values may be written in Persian/Arabic and digits may use Persian/Arabic-Indic numerals. This adds real meaning beyond the schema's type and description fields.

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

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

The description states a specific verb and resource: 'Add a new canned response to the account.' This clearly distinguishes it from sibling operations like list, update, and remove. However, it does not explicitly name or contrast with any sibling alternative in the text, 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 description provides no guidance on when to use this tool versus alternatives such as gapify_update_canned_response or gapify_list_canned_responses. It states what the tool does but offers no context, prerequisites, or exclusions to help an agent select it over 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 that this is a non-read-only, open-world, non-idempotent, non-destructive write operation. The description adds useful operational context beyond annotations: the auth header, the exact POST endpoint, the extra_body passthrough mechanism, and the Persian/Arabic-Indic digit handling. It does not cover duplicate-name behavior or rate limits, but it is more transparent than most mutation-tool descriptions.

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 and then layers endpoint, auth, body fields, and the i18n note in a compact paragraph. It is efficient overall, though the body-field enumeration duplicates what the schema already lists.

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 write API wrapper with no output schema, the description covers auth, endpoint, parameter surface, extra_body, and input language handling. Annotations cover the safety profile, so the remaining omission around error/response behavior is acceptable, though not fully complete for an agent expecting side-effect detail.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters and the 3 baseline applies. The description adds cross-cutting meaning that the schema does not provide, notably how text values may be Persian/Farsi and how IDs/numbers may use Persian or Arabic-Indic digits, plus the extra_body merge behavior. It mostly restates field names, but the language/digit note is meaningful parameter 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 a specific verb and resource: 'Add a category to a help center portal.' It distinguishes this from sibling tools like gapify_add_portal and gapify_add_article by naming the exact resource (category) and scope (help center portal), so an agent can select it 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?

Usage is implied by the tool name and the phrase 'Add a category to a help center portal,' but there is no explicit guidance on when to use this versus related tools. No alternatives or exclusions are named, so the agent must infer the correct context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the description's job is lighter. It adds real value beyond them: the auth header required, the exact request path, the accepted body fields, and the note that Persian/Arabic-Indic text and digits are sent unchanged, which matters for data integrity.

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

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

It is front-loaded with the action, then gives endpoint, auth, body fields and the encoding caveat in a compact block. No filler sentences, though the field list slightly duplicates the schema.

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

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

For a creation tool with 8 parameters, a nested extra_body object and no output schema, the description supplies the auth method, the endpoint, the mappable body fields and the escape hatch for extra fields. It does not describe the response or error behavior, which is the main remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the display-type and model enumerations. The description restates the body field names but adds no semantics beyond that, apart from the language/digit handling note; baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Add a new custom attribute') and includes the concrete endpoint, so the agent knows exactly what is created. It is distinguishable from siblings like list/get/update/remove_custom_attribute, though it never names them explicitly.

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

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

Usage is implied by 'Add a new' versus the sibling update/remove tools, but there is no explicit statement of when to prefer this tool over gapify_update_custom_attribute or what prerequisites exist. The requirement of a User API key is stated, which helps a little.

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

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

Goes beyond the annotations (which only declare non-read-only, non-destructive, non-idempotent) by disclosing the required auth mechanism (User API key via `api-access-token` header), the underlying endpoint, and that values are transmitted unchanged including Persian/Arabic-Indic digits. It does not state what happens to existing members or how failures are surfaced, but it adds real context the annotations do not.

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

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

Front-loads the purpose, then layers endpoint, auth and body details compactly with no filler sentences. The bracketed '[Inboxes]' tag and the language note are slightly redundant but not wasteful.

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

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

For a mutation tool with no output schema and full schema coverage, the description supplies endpoint, auth and body requirements, which is close to sufficient. It still omits the add-vs-replace semantics relative to gapify_update_inbox_agents and any error/edge behavior, leaving a gap an agent could get wrong.

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

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

Schema description coverage is 100%, so inbox_id, user_ids, account_id and extra_body are already documented; the description largely restates the required body fields. The one genuine addition is the note that text/ID values may be written in Persian or Arabic-Indic digits and are sent unchanged, which is a small semantic gain over the schema.

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

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

States a specific verb+resource ('Add agents to an inbox') and even names the endpoint POST /inbox_members, so the action is unambiguous. It does not, however, distinguish itself from close siblings like gapify_update_inbox_agents (which also mutates inbox membership) or gapify_remove_inbox_agent.

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

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

No explicit when-to-use or when-not-to-use guidance. The agent must infer that this is for adding members while gapify_update_inbox_agents replaces the membership set and gapify_remove_inbox_agent removes members; the description never says so, leaving the add-vs-update choice to guesswork.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds real value beyond them: the auth mechanism (User API key in `api-access-token`), the exact endpoint, and the extra_body merge behavior. It stops short of disclosing error/duplicate-slug behavior, 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?

Front-loaded with the purpose, then endpoint/auth/body fields in a compact block. The enumerated body-field list is somewhat redundant given 100% schema coverage, but it is short and the extra_body and localization notes earn their space.

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

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

For a mutation tool with 11 params, one required, no output schema, and annotations covering the safety profile, the description supplies auth, endpoint, payload shape, and a passthrough mechanism. It omits the required-parameter note and any hint of return/error behavior, so it is not fully complete but is close.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by documenting the extra_body passthrough and, notably, the localization rule that text may be Persian/other languages sent unchanged and that IDs/numbers may use Persian or Arabic-Indic digits — value the schema does not carry.

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: 'Create a help center portal in the account.' That cleanly separates it from gapify_list_portals and gapify_update_portal, though those siblings are never named explicitly, so differentiation is inferred from the verb 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?

Usage is implied by the verb and the API endpoint shown, but there is no explicit when-to-use/when-not guidance or routing to alternatives (e.g. update_portal for existing portals). The auth note and extra_body escape hatch add practical context but not selection 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 safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), so the bar is lower. The description still adds real context beyond them: the auth mechanism (User API key in api-access-token header), the concrete endpoint, and the extra_body merge behavior. It stops short of describing duplicate-membership behavior, so it is not a 5.

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

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

Purpose is front-loaded and the API/auth details are compact, but the trailing note about Persian/Arabic-Indic digits and unchanged text is boilerplate noise that does not earn its place for an ID-based membership call.

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

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

For a mutation tool with no output schema, the description covers the endpoint, auth, required body field, and an escape hatch (extra_body), which is adequate to invoke it. It is silent on the response shape and on what happens when a user is already a team member, leaving gaps for a non-idempotent write.

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

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

Schema coverage is 100%, so the schema already documents account_id, team_id, user_ids, and extra_body, making 3 the baseline. The description restates user_ids as required and mentions extra_body but adds no format or constraint detail beyond what the schema provides.

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

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

States a specific verb+resource (add agents to a team) that is immediately distinguishable from the sibling operations list_team_agents, update_team_agents, and remove_team_agent. An agent can tell what this does 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 text is an API reference rather than guidance: it never says when to use this versus update_team_agents or the similar gapify_add_inbox_agents, nor does it state any preconditions. No when-to-use, when-not-to-use, or alternative is given.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), so the bar is lower. The description adds real value beyond that: required auth header, HTTP endpoint, body field set, the extra_body escape hatch, and the Persian/Arabic-Indic digit handling for inputs. It stops short of stating behavior on duplicate URLs or success/error responses.

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, then auth and body details follow in a compact block. Every sentence carries information (endpoint, auth, fields, encoding note); it is dense but not padded.

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

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

With no output schema and annotations covering the safety profile, the description is nearly self-sufficient: it supplies endpoint, auth mechanism, required body fields, and encoding caveats. It could go further on valid subscription event values and failure behavior, but 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%, so the schema already documents url, account_id, subscriptions, and extra_body, making 3 the baseline. The description restates the body fields and notes the language/digit-input flexibility, which adds minor context but no syntax the schema lacks.

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 webhook subscription to the account') and the endpoint. It is clearly distinguishable from siblings gapify_list_webhooks, gapify_update_webhook, and gapify_delete_webhook, which cover the other CRUD operations.

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

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

Usage is implied by the create verb, but the description never states when to add a webhook versus updating or listing them, nor any prerequisites beyond the auth key. No alternatives or exclusions are named, so guidance remains 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 read-only, idempotent, open-world, non-destructive profile, so the bar is lower. The description still adds real context beyond them: the required User API key auth header (api-access-token) and the note that text/IDs may arrive in Persian or Arabic-Indic digits and are passed through unchanged — behaviorally relevant for invocation.

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

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

The core purpose is front-loaded in the first line, with endpoint and auth details following compactly. The Persian/Arabic-Indic digit note is niche but short, and everything is stated without padding or repetition.

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

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

Auth, endpoint, and the Digit/language quirk are covered, and annotations carry the safety profile. The main gap is that with no output schema, the description never indicates which conversation metrics are returned or their shape, leaving the agent unable to anticipate the result.

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

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

Schema description coverage is 100%, so the schema already documents account_id, type, and user_id. The description adds nothing about parameter meaning, format, or the 'type=agent' enum value beyond what the schema provides, so it lands at the baseline for well-covered schemas.

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

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

The description states a specific verb and resource ('Get conversation metrics for Agent') and anchors it with the endpoint path GET /reports/conversations/, so the agent knows exactly what it does. However, it does not distinguish itself from near-siblings like gapify_account_conversation_metrics or gapify_get_account_reports_summary, leaving ambiguity about which report endpoint to pick.

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

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

The '[Reports]' tag and 'Agent' scoping imply this is for agent-level reporting, but there is no explicit when-to-use or when-not-to-use guidance, and no named alternative among the several report-related siblings. Usage is only implied, not stated.

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

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

Annotations already declare mutating (readOnlyHint=false), non-idempotent, non-destructive, open-world behavior. The description usefully adds the auth requirement (User API key header) and language/digit handling context, but does not say what a reassignment replaces, whether the prior assignee is notified, 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 core purpose is front-loaded, followed by endpoint, auth, and param notes in a compact block. It is somewhat dense (mixing endpoint/auth/body/language into one paragraph) but no sentence is truly 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 mutation tool with no output schema, the description covers endpoint, auth, body fields, and passthrough but omits success/return behavior and side effects. Adequate to invoke but incomplete on outcome expectations.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates body fields (assignee_id, team_id) and the extra_body passthrough that the schema already documents in detail, adding little beyond the schema.

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

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

The description states a specific verb and resource ("Assign a conversation to an agent or a team") and even includes the exact REST endpoint, making scope unambiguous. It distinguishes itself clearly from siblings like create_conversation or toggle_conversation_status.

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

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

It never says when to use this tool versus alternatives, nor does it state prerequisites or exclusions. The only conditional behavior (team_id ignored when assignee_id is present) is in the schema, not framed as guidance in the description.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds real behavioral context beyond that: the extra_body merge escape hatch, and that text is sent unchanged in any language while Persian/Arabic-Indic digits are accepted in IDs and phone numbers. It still omits error/duplicate behavior and auth requirements for identifier_hash.

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

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

Front-loaded with the verb and endpoint, which is good, but the enumeration of body fields duplicates the schema almost verbatim and consumes most of the description without adding meaning. The language/digit sentence is the only part that clearly 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 create-mutation with no output schema, the description covers the endpoint and inputs but says nothing about the response (created contact payload), error conditions such as duplicate identifiers, or required permissions. Annotations cover the safety profile, so the gap is moderate rather than severe.

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

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

Schema description coverage is 100%, so the schema already documents each field and the baseline is 3. The description largely re-lists the same fields, though the note about Persian/Arabic-Indic digits in IDs, numbers and phone numbers adds genuine input-format semantics the schema does not carry.

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 contact') and pins it to a concrete endpoint (POST /public/api/v1/inboxes/{inbox_identifier}/contacts), so the agent knows exactly what happens. It does not distinguish itself from the sibling gapify_create_contact or gapify_client_create_contact, leaving the agent to infer which API surface applies.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no mention of the near-identical siblings gapify_create_contact / gapify_client_get_contact / gapify_client_update_contact. The agent must guess whether this is the public-API variant or the conversational-client variant.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the description need not restate them. It adds some real context: the endpoint path, the ability to pass extra body fields via extra_body, and the fact that text and digits are forwarded unchanged. It says nothing about auth requirements, duplicate handling, or what a successful creation yields.

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

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

The core action is front-loaded in the first clause, followed by the endpoint and body information in a compact block. The Persian-digit sentence is somewhat tangential but is relevant to how input values are handled, so it earns its place.

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

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

With no output schema and a mutation tool, the description should carry more of the behavioral burden. It covers the endpoint, the body shape, and the extra_body escape hatch, but omits error conditions, authentication expectations, and any notion of what the call returns, leaving gaps for a non-idempotent create operation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, making 3 the baseline. The description's only additive note is that values may be supplied in Persian or Arabic-Indic digits and are sent unchanged, which is a marginal semantic detail rather than a substantive clarification of inbox_identifier or contact_identifier.

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 conversation') and even pins the exact REST endpoint, which removes ambiguity about what is being created. However, it never distinguishes this client-scoped variant from the sibling gapify_create_conversation, so an agent must infer the difference from the '[Conversations API]' tag and the inbox/contact path.

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 the closely related sibling gapify_create_conversation. An agent choosing between the two create-conversation tools gets no routing signal.

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

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

Annotations already declare the safety profile (write op, non-idempotent, non-destructive, open-world). Beyond that, the description usefully discloses that text is sent unchanged and that Persian/Arabic-Indic digits are accepted for IDs and numbers, plus the extra_body merge mechanism. It omits auth requirements and error behavior, 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?

Front-loaded with the action, then the endpoint, then body fields, then the language/digit note. It is appropriately short and every sentence carries information; the Persian/Arabic-Indic note is slightly tangential but plausibly useful for this locale-focused API.

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 6-parameter mutation tool with no output schema, the description covers the call surface (endpoint, body fields, extra_body) but says nothing about what a successful create returns, error modes, or that echo_id comes back over websockets (only in the schema). Adequate but with clear 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 100%, so the schema already documents content, echo_id, extra_body and the three identifiers in detail; baseline is 3. The description restates the body fields (content, echo_id) and clarifies the extra_body escape hatch, but adds little beyond the schema's own descriptions.

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

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

States a specific verb+resource ('Create a message') and even gives the full POST endpoint path with the resource hierarchy, so the agent knows exactly what it does. However, it never distinguishes this 'client' message creation from the sibling gapify_create_message, leaving the split between the two API surfaces to inference.

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

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

There is no when-to-use guidance, no prerequisites (e.g. that a conversation must exist first), and no named alternative among the many message-related siblings (gapify_create_message, gapify_client_update_message). The endpoint path implies context but provides no explicit routing advice.

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 clear. The description adds a useful caveat that text and numeric identifiers may use Persian/Arabic-Indic digits, but it does not describe return format, error behavior, or authentication needs.

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

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

The description is front-loaded with the operation and resource, then adds a relevant caveat. It contains no filler, though the raw endpoint is somewhat redundant with the schema.

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

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

For a simple two-parameter read tool, the description plus rich annotations and full schema coverage is largely sufficient to call it. It still lacks sibling differentiation and does not explain what contact details are returned, which would help an agent use the result.

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

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

Schema description coverage is 100%, so both required parameters are fully documented there. The description mirrors the endpoint placeholders and adds a note about digit encoding, but provides no per-parameter meaning beyond what the schema already supplies.

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 the details of a contact') and includes the API endpoint, making the basic operation clear. However, it does not differentiate this client contact fetch from similar siblings like gapify_get_contact or gapify_list_contacts.

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

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

The description gives no explicit when-to-use, when-not, or alternative guidance. An agent must infer that this tool is for retrieving a known contact rather than listing or searching.

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 carried by structured data. The description adds real value beyond that with the endpoint path (confirming a single-resource fetch) and the note that Persian/Arabic-Indic digits may appear in IDs and numbers unchanged, which is useful for input normalization. It still says nothing about response content or error behavior.

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

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

The purpose is front-loaded in the first clause, followed by the endpoint and a compact encoding note. It is appropriately short and every sentence carries some information, though the Persian/Arabic-Indic digit note reads as boilerplate and slightly dilutes focus.

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

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

With no output schema, the description remains the only source for return-shape information, and it never says what "details" an inbox returns. For a single-parameter read tool whose annotations already cover the safety profile, this is adequate but leaves a real gap around what the caller receives.

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

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

Schema description coverage is 100% for the single inbox_identifier parameter, so the baseline is 3. The endpoint path in the description implicitly confirms it is a path parameter, but no additional syntax, format, or sourcing guidance is provided beyond what the schema already states.

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

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

The description states a specific verb+resource ("Get the details of an inbox") and even pins the underlying endpoint, so the operation is unambiguous. However, the sibling list contains gapify_get_inbox as well as gapify_list_inboxes, gapify_create_inbox, and gapify_update_inbox, and nothing in the description distinguishes this "client" variant from the platform-side get. The purpose is clear but sibling differentiation is absent.

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 stated prerequisites, and no named alternative. The description does not tell an agent when to prefer gapify_client_get_inbox over gapify_get_inbox or gapify_list_inboxes, which is exactly the ambiguity a sibling-heavy toolset creates.

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 real context beyond that: the required auth scheme ('User API key' in an `api-access-token` header) and the caveat that Persian/Arabic-Indic digits and multilingual text pass through unchanged, which matters for matching identifiers and output.

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

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

Front-loads the purpose in one sentence, then gives endpoint, auth, and an encoding caveat compactly. The digit/language sentence is somewhat boilerplate for a list call but is short and does not bloat the definition.

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

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

Covers scope and auth adequately for a read-only list call, but with no output schema it says nothing about the return shape, pagination, or whether empty results are possible. An agent knows how to call it but not what to expect back.

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

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

Schema coverage is 100% and both parameters are documented in-schema, so the baseline is 3. The description adds nothing about format beyond the URL template, and the multi-language digit note is at best tangential to how the identifiers should be supplied.

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 all conversations for the contact') and pins the scope via the GET path with inbox and contact identifiers. This distinguishes it from the broader gapify_list_conversations, though it does not explicitly contrast with the near-identical sibling gapify_list_contact_conversations.

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

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

Usage is only implied by the scoping path: you need an inbox and contact identifier, so it is for per-contact conversation retrieval. It never names when to prefer this over gapify_list_contact_conversations or gapify_filter_conversations, nor any prerequisites beyond auth.

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 behavior, so the bar is lower, and the description adds two concrete traits beyond them: the required auth header (api-access-token) and the data-encoding caveat that text may arrive in Persian and digits may be Persian/Arabic-Indic. It omits return shape and pagination behavior, keeping it out of the top band.

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

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

The core purpose is front-loaded in the first sentence, followed by the endpoint and auth, with the encoding caveat last. It is compact overall, though the Persian-digit sentence is somewhat tangential to listing messages.

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 list tool with no output schema, the description never indicates what is returned (message fields, ordering) or whether results are paginated/limited, which an agent needs before calling. Auth and encoding details are covered, but the return-side gap keeps this at minimum viable.

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

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

Schema coverage is 100%, so the schema already documents all three required identifiers and their meaning. The description adds only the endpoint template, which restates where each parameter belongs rather than adding new semantic detail, matching the baseline 3.

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

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

The description names a specific verb and resource ('List all messages in the conversation') and pins the resource with an explicit endpoint path showing the inbox/contact/conversation hierarchy. It does not, however, distinguish this client-facing tool from the platform sibling gapify_get_messages, so an agent can't route between them from the text alone.

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

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

Usage is only implied by the endpoint path and the 'User API key' auth note, which signals the public/client API scope. There is no explicit when-to-use, when-not-to-use, or reference to the sibling gapify_get_messages 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 the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description goes beyond them usefully by disclosing the extra_body merge mechanism and the fact that text is sent unchanged with Persian/Arabic-Indic digit support. It still omits whether unspecified fields are left intact (partial vs full update), which matters for a PATCH.

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

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

Front-loaded with the action and endpoint, followed by the body-field inventory and one encoding caveat; nothing is padded. The body-field enumeration is the weakest part since it repeats the schema, but it is brief.

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

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

No output schema exists, so return values need not be described, and all ten parameters are documented in the schema. What is missing is update semantics (partial vs full replace), auth/permission expectations, and any sibling disambiguation for a tool with several near-identical update neighbors.

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

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

Schema coverage is 100%, so the baseline is 3; the description lifts it by naming the accepted body fields as a set, explaining how extra_body carries unlisted keys, and adding an input-format rule for identifiers/numbers/phone numbers (Persian or Arabic-Indic digits). The field list itself is largely redundant with the schema.

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

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

States a specific verb and resource ('Update a contact's attributes') and pins down the exact HTTP method and path, so the agent knows this is an inbox-scoped PATCH. It does not, however, differentiate itself from the sibling gapify_update_contact, leaving the agent to infer which contact-update variant applies.

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

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

There is no when-to-use guidance, no statement of prerequisites (e.g. needing the inbox identifier from the inbox channel), and no routing to or away from the sibling gapify_update_contact or gapify_get_contact. The only context is the raw endpoint path, which the agent must interpret on its own.

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-readOnly, non-idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value with the encoding/language disclosure (values sent unchanged, Persian or Arabic-Indic digits accepted), but says nothing about permissions, side effects, or what the update returns.

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

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

Front-loads the action and endpoint, then lists body fields and the encoding caveat. Each sentence carries information; the endpoint URL is verbose but legitimately precise for a client API wrapper.

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

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

For a mutation tool with no output schema, the description covers inputs reasonably but omits what the response contains, what happens to unmodified message fields, and any auth requirements. Adequate but with clear 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 100%, so the schema already documents all six parameters thoroughly. The description reinforces submitted_values and extra_body and adds a genuinely useful note about Persian/Arabic-Indic digits being sent unchanged, but offers no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Update a message') and pins it to a concrete PATCH endpoint, so an agent can distinguish it from siblings like gapify_create_message and gapify_delete_message. It stops short of describing what aspects of a message are actually mutable beyond the submitted_values field.

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 update versus create/delete a message, and no prerequisites or alternative tools are named. The agent must infer usage entirely from the method name and path.

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/idempotency/open-world profile, but the description adds genuinely useful behavioral context: the required auth header, the exact endpoint, the extra_body merge escape hatch, and that non-Latin text and Persian/Arabic-Indic digits are passed through unchanged. That goes meaningfully beyond the structured fields.

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

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

Front-loaded with the purpose, then endpoint, auth, body fields and edge-case note in a tight block. No filler sentences, though the line-broken spec-style formatting is slightly dense.

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

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

For a create tool with no output schema, the definition covers auth, endpoint, body fields, the extra_body escape hatch and text/digit handling — enough to call it correctly. It stops short of stating what is returned or whether the new bot id is needed downstream.

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

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

Schema description coverage is 100%, so name, account_id, description, outgoing_url and extra_body are already documented at baseline 3. The description reiterates the three body fields and clarifies how extra_body works, but adds no format or constraint detail the schema lacks.

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 an agent bot in the account') and scopes it by HTTP endpoint, so the action is unambiguous. However it offers no differentiation from the near-duplicate sibling gapify_platform_create_agent_bot, leaving the agent to guess which create tool to pick.

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

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

It provides context ('Account AgentBots', endpoint path) but never says when to choose this tool over alternatives, nor any exclusions or prerequisites beyond the auth line. With a nearly identical sibling creator present, the absence of routing guidance is a real gap.

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

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the safety bar is low. The description adds real value beyond that: the required auth header, the exact endpoint, and the note that text/IDs are sent unchanged and may contain Persian or Arabic-Indic digits. It does not say what happens on a duplicate email or identifier, which matters for a non-idempotent create.

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

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

Front-loads the action and endpoint, then auth, then body fields -- a sensible order. The body-field list largely restates the schema, which is mild redundancy, but the added language/digit note justifies the length and nothing is padded.

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

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

For a 10-parameter write tool with nested objects, no output schema and no idempotency guarantee, the description covers endpoint, auth, required fields, field list, the extra_body escape hatch, and input encoding. What it omits is failure/duplicate behavior and the distinction from the client-side sibling, which are the remaining reasons an agent could still mis-call it.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every field. The description earns above baseline by adding input-format nuance the schema omits: values pass through unchanged, and identifiers/phone numbers may use Persian or Arabic-Indic digits, which directly affects how a caller should format inbox_id and account_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?

States a specific verb+resource ("Create a new contact in the account") and includes the endpoint, so the operation is unambiguous. However, it never distinguishes itself from the sibling gapify_client_create_contact, which addresses the same resource from a different API surface, so an agent cannot route between them from the description alone.

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

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

The description gives prerequisites (auth header, required inbox_id) but no when-to-use guidance and names no alternative. The critical ambiguity -- gapify_create_contact vs gapify_client_create_contact -- is left entirely unaddressed, and no note about duplicates or pre-checks is offered.

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, non-idempotent, openWorld; the description goes further by naming the auth mechanism and exact header (api-access-token), disclosing the extra_body escape hatch, and warning that text may be Persian/Farsi and digits may be Arabic-Indic and are passed through unchanged — a genuinely useful non-obvious behavior. It stops short of saying what happens on duplicate creation or what the response contains.

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

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

Front-loaded with the core action before endpoint/auth/body details, and each sentence carries information. The HTTP verb/path line is somewhat redundant with the tool name, and the Farsi/digit note is lengthy, but nothing is wasted.

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

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

For a mutation tool with no output schema, the description covers auth, required body fields, the extra_body mechanism and an encoding caveat, and annotations carry the safety profile. It omits return shape and failure/duplicate behavior, but is usable as written for a 5-parameter endpoint.

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

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

Schema description coverage is 100%, so the schema already documents id, inbox_id, source_id, account_id and extra_body. The description restates the body fields and marks inbox_id required, adding minimal semantics beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a contact inbox record for an inbox') and reinforces it with the exact endpoint POST /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes. This is clearly a join/link operation distinct from gapify_create_contact, though it never explicitly contrasts itself with sibling tools like get_contactable_inboxes or create_contact.

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

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

Usage is implied by the resource name and the required path components (account_id, id, inbox_id), so an agent can infer you need an existing contact and inbox. However, there is no explicit when-to-use statement, no prerequisite note (e.g., that the contact must already exist, or when to prefer this over assigning an inbox another way), and no alternatives named among the many sibling tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true. The description adds valuable context beyond those annotations: required auth headers (User API key or Agent bot API key), support for extra_body, and the fact that Persian/Arabic-Indic digits are accepted in IDs and numbers.

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

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

The description is front-loaded with the purpose and then provides useful operational details (endpoint, auth, body fields, extra_body, language note). It is reasonably concise for an 11-parameter tool, though the body-fields list partially duplicates what the schema already provides.

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 11 parameters, nested objects, no output schema, and the available annotations, the description covers the essential context: purpose, required fields, auth, endpoint, extra_body, and language/digit handling. It omits account_id as a required path parameter in the body-fields list, but that is implied by the endpoint, and no output schema exists to explain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that source_id comes from gapify_create_contact_inbox and by noting language and digit handling for text values, which is not captured in the schema.

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

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

The description states a specific verb and resource: 'Create a conversation for a contact in an inbox.' It also gives the exact endpoint and required source_id. However, it does not explicitly differentiate this from the sibling gapify_client_create_conversation, which is the most similar alternative.

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

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

Usage context is implied by the prerequisite note '(see gapify_create_contact_inbox)' and the auth requirements, but there is no explicit guidance on when to choose this tool versus gapify_client_create_conversation or gapify_create_message, nor 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 the write profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the safety bar is partially met. The description adds genuine context beyond annotations: the required auth header ('api-access-token'), the exact endpoint, that extra keys go through extra_body, and that Persian/Arabic-Indic text and digits are passed through unchanged.

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

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

Front-loaded with the purpose, followed by endpoint, auth, and body-field notes in a compact block. Every line carries information, though the encoding/language note is somewhat tangential for a create call.

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

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

For a non-idempotent create tool with no output schema, the description supplies endpoint, auth requirement, body fields, and an encoding caveat, while annotations carry the safety profile. An agent has enough to invoke it correctly; only a note on what a successful create returns or whether the name must be unique is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the type enum values and extra_body. The description recaps the main body fields (name, type, query) and mentions extra_body, adding marginal value but no syntax or semantics the schema lacks. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a custom filter in the account') and even names the API endpoint. It clearly distinguishes the create operation from siblings like gapify_update_custom_filter and gapify_list_custom_filters by virtue of the verb, though it never explicitly references them.

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

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

Usage is implied: this is the tool to add a new saved filter. There is no explicit when-to-use versus update/delete/get, no prerequisites, and no guidance on choosing between creating a filter here vs using a list/filter query tool. Implied rather than stated.

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

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

Annotations already declare the write/idempotency/open-world profile, so the bar is lower, yet the description adds real context beyond them: the required User API key header, the fact that extra_body fields are merged into the request, and the unusual behavior that Persian/Arabic-Indic text and digits are forwarded unchanged. It does not say what the call returns, which is the remaining gap.

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

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

Front-loaded with the purpose, then compactly layers endpoint, auth, body fields, and encoding notes; every sentence carries information. Slightly dense but no filler.

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

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

With no output schema, nothing tells the agent what a successful create returns (e.g., the new inbox ID) or what errors to expect, which matters for a non-idempotent mutation that downstream calls must reference. Auth, body, and encoding are otherwise covered adequately for a 5-param tool.

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

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

Schema description coverage is 100%, so a 3 is the baseline, but the description adds semantics the schema lacks: which body fields are accepted (name, avatar, channel), the escape hatch via extra_body, and the language/digit normalization behavior for text and numeric values.

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

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

The description gives a specific verb+resource ("Create a new inbox (channel) in the account") and even names the endpoint, so an agent knows exactly what operation this is. It is distinguishable from the read/list siblings by the verb, though it does not explicitly contrast with the nearby gapify_create_contact_inbox, which is a different resource.

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

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

Usage is only implied by the create verb; there is no statement of when to prefer this over alternatives such as gapify_client_create_inbox or gapify_raw_request, and no prerequisites or exclusions. The auth header note gives useful context but not when-to-use guidance.

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

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

Annotations already declare the safety profile (non-readOnly, non-destructive, openWorld, non-idempotent), so the bar is lower. The description adds real value beyond them: the required auth mechanism (User API key in an `api-access-token` header), the extra_body passthrough behavior, and the Persian/Arabic-Indic digit handling. It still omits response behavior, but that is a minor gap against annotation coverage.

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

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

Compact and front-loaded, leading with the create action before the endpoint path, auth, fields, and notes. The POST path and header details are functional rather than filler, though the block is somewhat dense.

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

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

For a create-style mutation with no output schema, the description covers auth, body fields, the extra_body escape hatch, and an important input-encoding quirk. Annotations handle the safety profile, so the remaining omission of return/pagination behavior is acceptable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the body fields (app_id, inbox_id, settings) and explains extra_body, matching the schema, but adds no syntax or format detail beyond what the schema already documents.

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 an integration hook') that clearly distinguishes it from sibling update/delete/list integration tools. However, it never explicitly names an alternative or clarifies scope beyond the verb, so it stops short of a 5.

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

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

There is no when-to-use vs when-not-to-use guidance, no prerequisites, and no routing to alternatives like gapify_update_integration_hook or gapify_delete_integration_hook. The listing of body fields and the inbox_id hint imply scope but provide no usage direction.

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/non-idempotent/open-world profile, and the description adds genuinely new behavioral context: auth requirements (User API key or Agent bot API key via api-access-token header), the extra_body escape hatch, and the encoding rule for Persian/Arabic-Indic digits. It doesn't cover rate limits or return behavior, but adds real value beyond 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?

Purpose is front-loaded, followed by endpoint, auth, and field summary. It is dense with technical detail but each clause (auth, body fields, extra_body, digit handling) carries information, 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 create-message tool with no output schema and full schema coverage, the description supplies the required-parameter emphasis, auth modes, and language handling. Return-value behavior is unspecified but not needed given no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters thoroughly; the baseline is 3. The description lists the body fields and clarifies extra_body but adds little syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Send a new message or private note in a conversation') and anchors it with the concrete endpoint POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages. An agent can immediately distinguish this from read siblings like gapify_get_messages and delete_message.

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

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

Usage is implied by the purpose and endpoint, but there is no explicit when-to-use vs the very similar gapify_client_create_message or gapify_raw_request. No exclusions or conditions are stated, leaving routing to inference.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, open-world write. The description adds real context beyond that: the required User API key header, the extra_body merge behavior, and how Persian/Arabic-Indic text and digits are handled. It omits return/side-effect details, but the annotation baseline lowers the burden.

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

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

Front-loads the purpose, then auth, body fields, and encoding notes. Mostly compact, though the raw POST path and full endpoint add some implementation noise for an agent that only needs the action and inputs.

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

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

For a 5-parameter create tool with a nested extra_body object and no output schema, the description covers auth, the body contract, and the passthrough mechanism well. It does not describe the created resource's shape, which is a minor gap given no output schema exists.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description restates the body field names (name, description, allow_auto_assign) and clarifies that account_id is a path element, but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a team in the account'), which cleanly distinguishes it from the get/update/delete/list team siblings. It does not explicitly name an alternative, but the action itself 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?

Usage is only implied by the verb 'Create'; there is no explicit when-to-use vs. when-not guidance or reference to sibling tools such as gapify_update_team or gapify_list_teams. The note about extra_body hints at an escape hatch but does not frame usage conditions.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered structurally. The description still adds real value beyond them: the auth requirement (User API key in the api-access-token header) and the explicit confirmation that the deletion is permanent. It stops short of describing side effects on conversations or inboxes referencing the bot.

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

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

Front-loaded with the action, then the endpoint and auth in tight sentences with no wasted prose. The Persian/Arabic-Indic digit note is boilerplate but is short and operationally relevant, so it earns its place.

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

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

For a two-parameter destructive DELETE with full-100% schema coverage and no output schema, the description supplies the action, endpoint, auth header and permanence warning — everything needed to invoke it correctly. Only cascading-effect details are absent, which is a minor omission given the annotation coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely useful encoding guidance — IDs and numbers may be supplied with Persian or Arabic-Indic digits — which directly affects how account_id and id should be formatted. This is meaning the schema does not convey.

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 an agent bot from the account') plus the exact endpoint, so the action and scope are unambiguous. However, with near-identical siblings like gapify_platform_delete_agent_bot and gapify_remove_agent in the list, the description never explains what distinguishes this account-level bot deletion from 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 only guidance is the 'Destructive' warning; there is no statement of when to use this tool versus gapify_platform_delete_agent_bot or gapify_remove_agent, nor any prerequisite or caution about irreversibility beyond the single word. An agent gets no routing logic from the text.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'permanently deletes' line mostly reinforces existing signal. It does add genuine value beyond the structured fields: the required auth header (api-access-token / User API key) and the note that Persian/Arabic-Indic digits are accepted unchanged.

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

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

Front-loads the core action ('Delete a contact by ID') and keeps supporting detail in short lines. The raw HTTP endpoint line is slightly redundant with the operation, but overall it is efficient and well ordered.

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

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

For a two-parameter destructive delete with no output schema, the description covers the essentials: destructive permanence, auth requirements, and ID formatting. It stops short of stating what happens to dependent contacts or conversations, but is close to complete for this operation.

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

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

Schema coverage is 100%, so both parameters (id, account_id) are already documented in the schema. The description adds only the digit-format note about IDs and numbers, which is a modest format hint rather than new parameter meaning. Baseline 3 is appropriate.

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

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

States a specific verb (Delete), resource (contact), and key (by ID), immediately distinguishable from siblings like gapify_update_contact, gapify_get_contact, and gapify_create_contact. An agent can identify the correct 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 description says what it does but gives no when-to-use framing, no prerequisites, and never references the parent-account scoping or any alternative. Usage is only implied by the operation name, which is the minimum viable level.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description corroborates with explicit permanence ('permanently deletes the resource') and adds the auth requirement (User API key in the api-access-token header), which annotations do not carry. It does not say what happens when the ID does not exist, so it stops short of full coverage.

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

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

Front-loaded with purpose and endpoint, then auth and destructiveness, which is good ordering. The trailing locale/digit sentence is only marginally relevant to a two-ID delete and slightly dilutes an otherwise tight definition.

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

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

For a simple two-parameter delete with no output schema and annotations covering safety, the description supplies purpose, endpoint, auth, and permanence. Missing only edge-case behavior (non-existent filter, cascading effects), which is minor here.

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

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

Schema description coverage is 100%, so both IDs are already documented by the schema; baseline is 3. The Persian/Arabic-Indic digit note adds a small amount of format guidance for the ID values but nothing about type coercion or the string/number union.

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 filter from the account') and pins the exact endpoint DELETE /api/v1/accounts/{account_id}/custom_filters/{custom_filter_id}. The resource is unambiguous against siblings such as delete_contact, delete_team, or update_custom_filter.

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

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

Usage is implied by the name and the CRUD context, but the description never states when to delete versus update/remove, nor any prerequisite such as needing the filter to exist first. No alternative tool is named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds value beyond them: the required auth mechanism (User API key in the `api-access-token` header) and the permanence wording. It doesn't cover error/permission behavior, but the auth disclosure is genuine added 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?

Front-loads the action and endpoint, then layers auth and destructiveness notes concisely. The trailing multilingual/digit boilerplate is generic padding but not enough to derail the structure.

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

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

For a two-param delete with no output schema, the description covers the essentials an agent needs to call it: identity, endpoint, auth, and destructiveness. Missing only permission/failure behavior, which is a minor gap here.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a relevant encoding nuance: IDs and numbers may be submitted with Persian or Arabic-Indic digits, which directly affects how the required hook_id/account_id values can be formatted.

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 an Integration Hook') and pins it to the exact endpoint DELETE /integrations/hooks/{hook_id}, which cleanly separates it from the sibling create/update/list integration hook 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 signals destructiveness ('this permanently deletes the resource'), which implies caution, but gives no explicit when-to-use-vs-alternatives guidance (e.g. prefer update_integration_hook to modify, delete only to remove permanently). Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the deletion also removes attachments, the auth requirement (User API key via `api-access-token` header), and that deletion 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?

Purpose is front-loaded in the first sentence, followed by the endpoint and auth note. The 'Destructive: this permanently deletes the resource' line partially repeats the destructiveHint annotation, and the Persian/Arabic-Indic digit note reads as generic boilerplate, but overall the description stays 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?

For a simple delete with no output schema and full annotation coverage, the description is nearly complete: it states the resource, the cascading attachment removal, permanence, and auth. It only lacks explicit usage routing against alternatives, which is minor here.

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

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

Schema description coverage is 100% with all three IDs documented, so the baseline is 3. The URL template implicitly maps account_id/conversation_id/message_id as path parameters, but the description adds no semantics (e.g., format or ID sources) beyond what the schema provides.

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

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

States a specific verb+resource: 'Delete a message and its attachments from a conversation'. This clearly distinguishes it from siblings like gapify_get_messages, gapify_create_message, and gapify_client_update_message, and the endpoint line reinforces exactly which resource is removed.

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 delete intent is implied and unambiguous for this operation, but the description offers no explicit when-to-use/when-not guidance or alternatives (e.g., that it cannot be undone, or that attachments are removed alongside the message). Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the auth requirement (User API key in `api-access-token` header) and reinforces permanence ('permanently deletes the resource'). The input-language/digit note is useful behavioral context for callers. It does not restate the idempotency trait, but the added auth detail is real value beyond structured data.

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

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

Purpose is front-loaded in the first clause, followed by endpoint, auth, and destructive warning in a tight sequence. The trailing Persian/Arabic-Indic digit note is somewhat generic boilerplate but still relevant to input handling.

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-param destructive delete with no output schema and full annotation coverage, the description supplies the endpoint, auth mechanism, and irreversibility warning. Nothing essential to correct invocation is missing, though a note on what happens to team members/agents would round it out.

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

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

Schema description coverage is 100%, so the schema already documents both required path parameters, and the endpoint string in the description confirms them. No additional syntax, format, or edge-case meaning is added, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Delete a team from the account') and even names the endpoint, so an agent can immediately distinguish it from gapify_create_team, gapify_update_team, and gapify_list_teams.

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

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

Usage is implied by the verb and the API endpoint, but there is no explicit guidance on when to choose this over alternatives or any prerequisite/warning workflow before an irreversible delete. For a destructive single-purpose tool this is adequate but unhelpful beyond the obvious.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds useful context beyond annotations by specifying the required auth header and noting that Persian/Arabic-Indic digits may be used, while also reinforcing permanence.

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 resource, then quickly covers endpoint, auth, destructive behavior, and language/digit handling. Every line adds operational value with no filler.

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

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

For a two-parameter destructive delete with rich annotations and no output schema, the description provides everything needed: purpose, auth, endpoint, permanence, and input-format caveat. There is no meaningful missing context for correct invocation.

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

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

Schema coverage is 100%, so the two required ID parameters are already documented. The description adds useful format guidance that IDs and numbers may use Persian or Arabic-Indic digits, which is directly relevant to account_id and webhook_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 description states a specific verb and resource: "Delete a webhook from the account," and the endpoint confirms the exact scope. It is clearly distinguishable from sibling tools such as gapify_list_webhooks, gapify_add_webhook, and gapify_update_webhook.

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 clear context for using this tool and explicitly warns that the operation permanently deletes the resource. It does not explicitly name alternatives or when-not-to-use guidance, but the delete-specific purpose makes the selection obvious among siblings.

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

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

Annotations declare a non-read-only, open-world, non-idempotent profile, and the description corroborates this by disclosing the raw HTTP surface (POST endpoint) and the auth requirement (User API key or Agent bot API key via `api-access-token` header). The Persian/Farsi and Arabic-Indic digit passthrough note is genuinely useful behavioral context not derivable from annotations or schema.

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

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

The definition is front-loaded with the purpose, then method, auth, and body fields in compact fashion. The closing digit-encoding sentence is somewhat tangential but short and adds distinct value; overall little waste.

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

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

With no output schema, the description supplies the endpoint, HTTP method, auth scheme, body-field pointer, and the extra_body escape hatch, which is adequate context for calling this nested-payload filter. Sibling differentiation is the main gap, but the mechanics of invocation are well covered.

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

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

Schema description coverage is 100%, so the schema already fully documents page, payload, account_id, and extra_body. The description only restates that 'payload' is the body field and that extra_body carries unlisted keys, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a clear verb+resource: 'Filter contacts with custom filter options and pagination.' This distinguishes it from plain listing, and the 'custom filter options' phrasing signals the structured payload approach. However it never names the alternatives (gapify_list_contacts, gapify_search_contacts), so the agent must infer the boundary itself.

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

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

Usage is only implied. The description mentions custom filter options and pagination but gives no explicit when-to-use or when-not-to-use versus siblings like search_contacts or list_contacts. Auth prerequisites and body-field naming are present, but routing guidance to alternatives is absent.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful non-schema behavior: dual auth paths (User API key or Agent bot key via api-access-token header), the concrete endpoint, extra_body merge semantics, and that Persian/Arabic-Indic digits are forwarded unchanged. It does not explain pagination limits or result shape.

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

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

Purpose is front-loaded in the first clause, with auth and body notes following in a compact block. Mild redundancy in 'Body fields: payload' since payload is fully specified in the schema, but no genuinely wasted sentences.

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

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

No output schema exists, but the description covers the operation, auth, endpoint and body-extension mechanism, which is most of what an agent needs. Gaps are minor: no note on pagination behavior/limits and no mention of the non-read-only annotation despite the filter semantics, though the schema example adequately carries the filter DSL.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents payload, page, account_id and extra_body with an example. The description goes slightly beyond the schema by flagging that text values pass through unchanged and that IDs/numbers may arrive in Persian or Arabic-Indic digits — a real encoding caveat not captured elsewhere.

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 ('Filter conversations') plus scoping qualifiers (custom filter options, pagination). It implicitly distinguishes itself from gapify_list_conversations by emphasizing custom filters, but never names the sibling or states the difference 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 implied: an agent can infer this is the tool for filtered/advanced conversation queries versus a plain list. There is no explicit when-to-use, when-not-to-use, or alternative routing among the several nearby conversation siblings (list_conversations, get_conversation_counts).

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

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

Annotations already declare readOnly/idempotent/openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: the required auth mechanism (User API key in the api-access-token header) and a data-encoding caveat about Persian/Arabic-Indic digits and unchanged text values.

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

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

Short and front-loaded: the core action leads, followed by endpoint and auth. The closing sentence on Persian/Arabic-Indic digits is a bit tangential to the tool's primary purpose but is legitimate I/O context and does not bloat the definition.

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

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

For a read tool with full parameter documentation and annotations covering the safety profile, the essentials are present. However, there is no output schema and the description only says 'time-series report data' without indicating the shape, granularity, or pagination behavior of the returned data, leaving the return contract underspecified.

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

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

Schema description coverage is 100%, and the schema already enumerates the allowed report types and metrics, so the description needn't repeat them. The description maps the conceptual inputs (metric, report type, date range) but adds no format or constraint detail beyond the schema, making the baseline of 3 appropriate.

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

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

States a specific verb and resource ('Get time-series report data for a metric, report type and date range') and names the endpoint. It implicitly distinguishes itself from the sibling gapify_get_account_reports_summary via 'time-series' vs. summary, but never names that sibling explicitly, so differentiation is inferential 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?

The phrase 'time-series report data' implies when this tool applies (trend/over-time queries versus a summary), but there is no explicit when-to-use guidance, no exclusions, and no mention of the closely related summary or metrics siblings. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering safety. The description adds useful behavioral context beyond annotations: authentication via User API key in the api-access-token header, the HTTP endpoint, and multilingual digit handling. It does not cover return format or pagination.

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 tool purpose, then endpoint and auth details. It remains reasonably tight, though the multilingual text/digit note is somewhat specialized and could be trimmed if not broadly relevant.

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

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

For a read-only summary endpoint with rich annotations and full schema coverage, the description covers purpose, auth, and endpoint. However, with no output schema, it does not explain the shape or contents of the returned summary totals, leaving a notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description only restates the report type and date range concepts without adding syntax, format, or edge-case meaning beyond the schema, matching the baseline 3.

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

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

States a specific verb (Get) and resource (summary report totals for a report type and date range), which distinguishes it from the sibling gapify_get_account_reports. It does not explicitly name or contrast with that sibling, which keeps it from a 5.

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

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

Usage is implied: use this when you need summary totals for a given report type and date range. There is no explicit when/when-not guidance or reference to the detailed-report sibling gapify_get_account_reports, so it remains only implied.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: the required auth scheme (User API key in an `api-access-token` header) and the fact that text values are sent unchanged and may contain Persian/Arabic-Indic digits or non-Latin characters.

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

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

The core purpose and endpoint are front-loaded in the first line, followed by compact auth and encoding notes. Every element is short and relevant, with no filler.

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

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

For a two-parameter read-only fetch with full schema coverage and rich annotations, the description covers purpose, endpoint, auth and data-encoding caveats. With no output schema present it could say a little more about the returned object, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented and a baseline of 3 applies. The description adds no further meaning about `id` or `account_id`, and notably does not correct the schema's misleading `id` description (it says 'agentbot to be updated' for what is a read-only fetch).

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

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

The description states a specific verb and resource ('Get the details of an agent bot in the account') and pins it to the exact REST endpoint, so the agent knows precisely what it retrieves. It does not, however, distinguish itself from the near-identical sibling gapify_platform_get_agent_bot, leaving the agent to guess which variant applies in the account-scoped context.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named despite multiple overlapping agent-bot getters in the sibling list. Usage is only implied by the endpoint path's account scope.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: the required User API key header (`api-access-token`) and the locale/numeral convention (Persian/Arabic-Indic digits accepted, text passed through unchanged). It omits behavior for a missing/invalid rule ID, 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?

The purpose is front-loaded in the first clause, and the endpoint, auth and encoding details are compact single lines. The API path and encoding boilerplate are somewhat mechanical, but nothing is redundant enough to penalize heavily.

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

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

With no output schema, the description should ideally convey what a returned automation rule contains or the failure mode for an unknown ID; instead it stops at endpoint, auth and encoding. For a simple two-parameter read it is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema documents both account_id and id. The description adds only the numeral-format note (Persian/Arabic-Indic digits allowed) for IDs; notably it does not correct the schema's misleading id description, which says 'the automation rule to be updated' on a read 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?

States a specific verb and resource ('Get an automation rule by ID') and even gives the underlying endpoint path, so the operation is unambiguous. It does not, however, explicitly distinguish itself from the sibling list/add/update/remove automation rule tools, 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 'by ID' framing implies this is the lookup tool for a single known rule, but there is no explicit guidance on when to use it versus gapify_list_automation_rules or gapify_update_automation_rule. Usage is inferable from the name rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value beyond that: the required auth scheme (User API key in the api-access-token header) and the unusual note that text may arrive in Persian and IDs/numbers may use Persian or Arabic-Indic digits, which materially affects how an agent should pass and interpret values.

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 operation, then the HTTP route, auth, and the locale caveat. Every element is relevant and there is no padding, though the endpoint/auth lines partly duplicate metadata an agent may already have.

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

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

With no output schema, the description should ideally say something about the returned contact shape or behavior when the ID is not found, and it does not. Annotations and the schema cover safety and inputs, so it is adequate but leaves a noticeable gap around return semantics.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents both account_id and id. The digit-encoding note adds genuine meaning for the id/account_id parameters that the schema does not convey, so a small bump above baseline is warranted.

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

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

States a specific verb and resource ('Get a contact by ID'), which cleanly separates it from list_contacts, search_contacts, and filter_contacts. It does not, however, distinguish itself from the near-identical sibling gapify_client_get_contact, so it falls short of a 5.

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

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

The 'by ID' phrasing implies the use case (single-record retrieval when the identifier is known), but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as search_contacts when the ID is unknown. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description usefully adds the required auth mechanism (User API key in the api-access-token header) and notes Persian/Arabic-Indic digit handling for inputs, going beyond the structured safety metadata.

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 clear sentence, followed by compact endpoint and auth lines. The final localization sentence is somewhat generic and not specific to this endpoint, but it is short and relevant to input formatting.

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

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

For a simple two-parameter read-only list tool, the description covers purpose, endpoint, auth, and input encoding. It does not describe the shape of the returned inbox list, which is a minor gap given no output schema exists, but the core information an agent needs to call it correctly is present.

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

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

Schema coverage is 100%, so the schema already documents account_id and id, making 3 the baseline. The description adds meaningful input-format context by noting that IDs and numbers may use Persian or Arabic-Indic digits, which directly affects how those parameters should be supplied.

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 (inboxes through which a contact can be reached), and includes the exact HTTP endpoint. It implies a contact-scoped filter, which separates it from gapify_list_inboxes, but it never explicitly names or contrasts with any sibling tool.

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 lets an agent infer that this is used when the reachable inboxes for a specific contact are needed, but it gives no explicit when-to-use guidance, prerequisites, or alternatives such as gapify_list_inboxes or gapify_create_contact_inbox.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the required auth mechanism ('User API key, header api-access-token') and the locale caveat about Persian/Arabic-Indic digits, which affects how IDs may be supplied.

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

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

Front-loads the purpose, then appends endpoint, auth, and encoding notes. Efficient, though the bracketed tag and raw GET path duplicate structured context.

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

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

For a simple two-required-param read tool with no output schema, the description covers what an agent needs to call it: purpose, endpoint, auth, and input encoding quirks. Return shape is unspecified, but no output schema exists to lean on.

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

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

Schema description coverage is 100%, so both required parameters are documented in the schema; baseline is 3. The description adds only tangential meaning (digits may be Persian/Arabic-Indic) and no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Get a conversation's details') that clearly distinguishes it from list_conversations, filter_conversations, and get_messages. Minor ambiguity: it says 'by its display ID' while the schema param is 'conversation_id' described as the numeric ID, so the identifier semantics are slightly loose.

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 read-only retrieval intent is implied but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives (e.g., use list_conversations to find the ID first). Usage must be inferred 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine context beyond them: the REST endpoint and the required auth header ('api-access-token'), plus a note that Persian/Arabic-Indic digits and non-English text pass through unchanged. It does not say what the returned counts look like or whether they are paginated.

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

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

Front-loaded with the purpose in the first clause, then endpoint, auth and encoding notes on separate lines. No filler sentences, though the Persian-digit note is boilerplate that sits oddly on a counts endpoint that returns no text values.

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

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

For a read-only aggregation with fully described parameters and no output schema, the definition is serviceable but leaves an important gap: it never describes the shape of the counts returned (per-assignment buckets vs. a single total), which is the single most useful thing to know before calling it.

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

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

Schema coverage is 100%, so all six filter parameters are already documented in the schema and the baseline is 3. The description adds little beyond 'optional filters', and it introduces an 'assignment' dimension (mine/unassigned/assigned/all) that has no corresponding schema parameter — potentially confusing rather than clarifying.

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 conversation counts') plus the grouping dimension (mine/unassigned/assigned/all) and the backing endpoint, so the agent knows exactly what it produces. It does not name or contrast with overlapping siblings such as gapify_filter_conversations or gapify_account_conversation_metrics, leaving the agent to infer which one yields counts versus records.

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?

'with optional filters' implies the filtering use case, and the assignment groupings hint at dashboard-style aggregation. However, there is no explicit when-to-use/when-not guidance and no pointer to alternatives, which matters given several conversation-listing siblings that could be mistaken for this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds context that the page is 'hosted' and that text values pass through unchanged and may use Persian/Arabic-Indic digits, which is genuinely useful input-handling context. It does not describe the returned survey structure or any failure modes.

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

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

The core purpose and endpoint are front-loaded in one sentence, which is efficient. The appended language/digit note is short but reads as boilerplate that is loosely related to the tool's actual purpose, slightly diluting focus.

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

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

For a simple read-only GET with one well-documented parameter and no output schema, the description conveys what is fetched and where. However, it says nothing about what the returned survey page contains (questions, scores, response state), which an agent would need to interpret the result.

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

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

Schema description coverage is 100%, so the single parameter is fully documented in the schema as 'The uuid of the conversation'. The description only restates this via the URL template ('/survey/responses/{conversation_uuid}'), adding no syntax, format, or validation meaning beyond what the schema provides. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Get the hosted CSAT survey page for a conversation') plus the underlying endpoint, so the agent knows exactly what it retrieves. It does not need to distinguish itself from a close sibling, since no other CSAT tool exists in the sibling list, but it also makes no explicit differentiation statement.

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

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

There is no explicit guidance on when to call this versus alternatives, nor any prerequisites (e.g. whether the conversation must be closed to have a survey). Usage is only implicit in 'for a conversation'. The trailing note about Persian digits is an input-format remark, not when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds the auth requirement (User API key via `api-access-token` header), which is real context beyond the annotations, but says nothing about errors, response shape, or rate limits.

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

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

The purpose is correctly front-loaded and the endpoint plus auth line are compact. The final sentence about Persian text and digits being "sent unchanged" is about writes and does not earn its place for a GET-by-ID tool, so the description carries irrelevant weight.

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

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

With only 2 fully documented parameters, complete annotations, and no output schema, the definition is functional but thin. Since no output schema exists, the description would ideally say what a custom attribute definition contains; it omits this entirely.

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

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

Schema description coverage is 100%, so the schema already documents both `id` and `account_id`; baseline is 3. The description adds no parameter-level meaning beyond the schema (and the trailing Persian/Arabic-Indic digit note concerns written values, not this read operation).

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 a custom attribute definition by ID") and scopes it to a single entity, which distinguishes it from the list/add/update/remove custom-attribute siblings. However, it does not name any sibling or explain the relationship to gapify_list_custom_attributes, so the differentiation is inferred rather than explicit.

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

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

The "by ID" phrasing implies the tool is for retrieving one known attribute rather than browsing, and the required `id` parameter reinforces this. But there is no explicit when-to-use guidance, no mention of when to prefer list_custom_attributes, and no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds context the annotations cannot: authentication via User API key in the `api-access-token` header, plus the note that text/ID values may arrive in Persian and are passed through unchanged. It stops short of rate limits or response size behavior, keeping it at a 4.

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

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

Purpose is front-loaded in the first clause, followed by the endpoint and auth requirement. The repeated bracket tag '[Custom Filters]' and the raw endpoint string are somewhat redundant with the name and schema, costing a point, but nothing is padded or 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?

For a two-parameter read tool with no output schema, the description covers the call mechanics (endpoint, auth) but never indicates what 'details' are returned, so an agent cannot anticipate the payload shape. Adequate but with a clear gap given the absence of an output schema.

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

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

Schema coverage is 100% — both account_id and custom_filter_id are self-documented as numeric IDs. The description's Persian/Arabic-Indic digit note is marginally relevant to how ID values may be encoded, but it is a generic API-wide caveat rather than semantics specific to these two parameters, so the baseline 3 for high schema coverage holds.

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 the details of a custom filter'), reinforced by the exact REST endpoint, so an agent knows this is a single-resource read keyed by account_id and custom_filter_id. It does not explicitly contrast itself with gapify_get_custom_filter's siblings like gapify_list_custom_filters or gapify_update_custom_filter, but the singular 'details' framing plus the ID path makes the distinction 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?

There is no when-to-use or when-not-to-use guidance and no alternatives named, so an agent must infer from the verb that this is the fetch-one-by-ID tool versus list_custom_filters. The auth line is a prerequisite, not usage routing, so it doesn't raise this dimension.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real value: the required auth mechanism (User API key in the api-access-token header) and the note that text/IDs may arrive in Persian or Arabic-Indic digits and are passed through unchanged. It does not describe error behavior or response shape, but the auth and encoding context is substantive.

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

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

Purpose is front-loaded in the first clause, and the HTTP path and auth line are compact and useful reference. The Persian/Unicode sentence is somewhat tangential but does carry format information, so it earns its place reasonably.

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

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

For a simple read-only lookup with full schema coverage and annotations declaring the safety profile, the description covers the essentials: what it fetches, the auth requirement, and input-format quirks. No output schema exists, so return values need not be explained, though error semantics are absent.

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

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

Schema description coverage is 100%, so both account_id and id are already documented and the baseline is 3. The digit-handling note ('IDs, numbers and phone numbers may use Persian or Arabic-Indic digits') adds input-format semantics beyond the schema, so it edges above baseline.

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

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

States a specific verb and resource (get an inbox in the current account), which is unambiguous on its own. However, it never distinguishes itself from the near-duplicate sibling gapify_client_get_inbox or from gapify_list_inboxes, so sibling differentiation is left to the agent.

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

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

There is no statement of when to use this tool versus the alternatives: nothing about when to fetch a single inbox by ID rather than list them, and nothing explaining the difference from gapify_client_get_inbox. Usage must be inferred entirely from the name.

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

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

The annotations already declare readOnly=true, idempotent=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds two useful operational facts beyond the annotations: the required auth header ('api-access-token') and that Persian/Arabic-Indic digit handling is passed through unchanged. It does not disclose pagination behavior or result volume, which matters for a list endpoint.

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

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

Front-loads the purpose in the first clause, then supplies endpoint and auth compactly. The trailing Persian/Arabic-Indic digit note is somewhat tangential but is genuinely relevant to text-bearing payloads and costs only one sentence.

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

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

For a two-parameter read-only list tool with no output schema, the annotations and 100% schema coverage carry most of the burden, and the description adds auth and text-encoding context. It still omits pagination or ordering behavior, which an agent calling a message-list endpoint would benefit from knowing.

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

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

Schema description coverage is 100% with both parameters already documented as numeric IDs, so the schema does the heavy lifting. The description adds no further semantics beyond echoing account_id and conversation_id in the URL template, matching the baseline of 3 for fully covered schemas.

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

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

States a specific verb+resource ('List the messages of a conversation') and the endpoint path makes the scope unambiguous. However it does not distinguish itself from the sibling gapify_client_list_messages, which appears to cover a similar surface, so the sibling differentiation is not fully resolved.

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

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

The description gives no when/when-not guidance and names no alternative (e.g. gapify_get_conversation, gapify_client_list_messages, or filtering helpers). Usage is only implied by the verb and endpoint path, which is minimal for a tool with this many 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 readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real context beyond that: the required auth scheme (User API key in the api-access-token header) and the encoding caveat about Persian/Arabic-Indic digits, which an agent handling responses would otherwise miss.

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

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

Front-loaded with the purpose in one sentence, followed by compact auth and encoding notes. The '[Profile] GET /api/v1/profile' line is mildly redundant REST metadata but costs almost nothing.

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

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

For a zero-parameter read tool with no output schema, the description covers purpose, target resolution, auth requirement and encoding caveats. The only gap is that it never hints at what fields the profile object contains, which an agent might want before relying on the result.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly conveys that no identifiers are accepted – the token itself determines the target – and adds the auth and numeral-encoding context relevant to using the response.

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

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

States a specific verb and resource: fetch the profile of the user who owns the API access token. The 'token owner' qualifier usefully distinguishes it from the many sibling get_user / get_contact / get_account tools, though no sibling is named explicitly.

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

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

Usage is implied by 'the user who owns the API access token' – this is the self-profile endpoint, not an arbitrary-user lookup – but there is no explicit when-to-use statement or pointer to gapify_platform_get_user as the alternative for fetching another user.

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 covered by structured data. The description adds genuinely new context: the required API-key auth header and the note that values may arrive in Persian/Arabic-Indic digits, which is real behavioral information not present in the schema.

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

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

The text is short and front-loaded, leading with the purpose before the endpoint, auth and encoding notes. The Persian-digits sentence is boilerplate that would apply to most tools in this server but is still 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?

With no output schema, the description would ideally describe what a team record contains, but it says nothing about the returned fields. It does cover the endpoint, auth requirement and encoding caveat, and annotations cover safety, so it is adequate but leaves a notable gap for a get-details tool.

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

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

Schema description coverage is 100%, so both parameters are already documented (account_id, team_id) and the baseline is 3. The description adds only the digit-encoding caveat for values, and notably the schema's team_id description says 'to be updated', a copy-paste error the description does not correct.

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

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

The description states a specific verb and resource ('Get the details of a team in the account') plus the underlying endpoint, so an agent immediately knows this is a single-team read operation. It does not explicitly contrast itself with the sibling tools gapify_list_teams or gapify_update_team, so no credit for 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?

There is no guidance on when to use this tool versus gapify_list_teams (to find a team_id) or gapify_update_team. The only contextual hint is the endpoint template showing both account_id and team_id are needed, which implies a prior lookup but never states it.

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