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

Annotations already declare idempotentHint=false and destructiveHint=false, so the description's 'Not idempotent: repeated calls add duplicate notes' restates that but usefully spells out the concrete consequence. Beyond the annotations, it adds that notes are internal/not customer-visible and that it returns the created note, which is genuine extra context.

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

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

Three tight sentences with no waste: purpose first, then the non-idempotency caveat, then the internal-vs-customer distinction and return value. Front-loaded and every sentence earns its place.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, idempotency behavior, audience/internal semantics, and return value. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters (text, lead_id) are already documented, including how to obtain the lead ID. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Add') plus resource ('plain text (common) note') and the target location ('a lead's timeline'). It also explicitly distinguishes itself from send_chat_message, so an agent can tell it apart from the messaging sibling without opening either schema.

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

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

Gives clear context and an explicit alternative: notes are internal and not sent to the customer, and send_chat_message is named for customer-facing messages. It does not cover other adjacent choices (e.g., task vs note), but the primary routing decision is unambiguous.

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=true, and destructiveHint=false, so 'Safe to repeat' largely restates structured data. However the description adds genuinely new behavior: the read-modify-write of the tag list that preserves existing tags, and the auto-creation of missing tags.

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

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

Four tight sentences, each carrying distinct information, with the core action front-loaded and the sibling pointer last. 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?

Explicitly states the return value ('Returns the updated lead'), covers idempotency and the tag-creation side effect, and points to list_tags. For a two-parameter mutation with no output schema, only minor details like failure modes are absent.

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

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

Schema coverage is 100%, including the lead_id source and case-sensitivity of tag_name, so the baseline is 3. The description only adds that tag_name may not exist yet and will be created, which is marginal 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 ('Attach a tag to a lead by name') and immediately clarifies a secondary effect (creating the tag when absent). This is easily distinguished from the sibling remove_tag and from generic lead writers.

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

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

Gives a clear condition ('Safe to repeat') and routes the agent to list_tags for discovering existing tag names. It does not explicitly contrast with remove_tag or explain the alternative of not tagging, but the context is clear.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the request is a single PATCH /leads, each element is merged from id + fields, and the batch Kommo response is returned. It stops short of describing partial-failure or invalid-ID 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?

Four short sentences, each carrying distinct information: transport, item composition, return value, and the sibling alternative. Nothing is redundant and the key facts are front-loaded.

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

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

No output schema exists, but the description states what the tool returns (the Kommo batch response), and the single nested parameter is well documented in both schema and prose. Only batch limits and error semantics are left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining how each array item is composed (fields merged with id) and cross-references update_lead for valid field keys, which the schema only alludes to.

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 many leads") plus the exact transport (PATCH /leads), making the batch nature explicit. It explicitly distinguishes itself from update_lead, so an agent can choose between them without opening either schema.

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

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

The closing sentence "Use update_lead for a single lead" gives an explicit routing rule to the nearest sibling. It does not cover any when-not conditions such as maximum batch size, partial-failure tolerance, or rate limits, but the core selection guidance is clear.

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 idempotentHint=false, readOnlyHint=false, and destructiveHint=false, so the safety profile is covered; the description reinforces the non-idempotency with a concrete consequence (duplicates are not checked) that the boolean alone doesn't convey, and notes it returns the created company. It does not mention auth requirements or rate limits, so it stops short of full transparency.

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

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

Three short sentences, zero filler, with the primary action stated first and the duplicate-lookup caveat immediately after. Every sentence carries actionable information.

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

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

For a one-parameter create tool with no output schema, the description covers the side effects, the pre-call check, the return value, and the sibling alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

There is exactly one parameter, and the schema documents it fully at 100% coverage with a concrete example, so the baseline is 4. The description's "name only" confirms the single-field shape but adds no syntax or validation 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 ("Create a company record") and bounds the scope with "with a name only." It is distinguishable from create_lead_complex and list_companies without opening either schema.

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

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

Gives explicit when-to-use guidance: look with list_companies first because duplicates are not checked, and names an alternative (create_lead_complex) with the condition that selects it. Both the exclusion and the alternative are stated.

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

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

Annotations already declare idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered; the description goes beyond them with the non-obvious duplicate behavior and the conditional silent-skipping of phone/email when PHONE/EMAIL fields are absent. That silent failure mode is exactly the kind of side effect an agent cannot infer from structured fields.

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

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

Front-loaded with the core action, then each subsequent sentence carries distinct load: idempotency caveat, prerequisite search, the conditional storage rule, the return value, and the sibling route. No sentence is redundant with another.

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 what is created, what is returned, when it silently drops data, and which sibling handles the combined case. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and the schema already documents all three parameters, so the baseline is 3. The description adds real semantics on top: email and phone are only persisted as WORK values when matching custom fields exist, which changes how the agent should treat a successful call with those arguments.

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 precise verb and resource ('Create one contact') and immediately distinguishes itself from the tempting alternative by naming create_lead_complex and list_contacts. An agent knows exactly which tool this is versus its siblings without opening the schema.

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

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

Explicitly tells the agent to run list_contacts first because the tool will not check for duplicates, and gives the condition for using the sibling instead ('To create a lead and contact together, use create_lead_complex'). Both when-to-use-this and when-to-use-something-else are covered.

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

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

Adds real behavioral context beyond the annotations: the non-idempotency consequence ('each call creates another field'), the cache-clearing side effect ('Clears the custom-field cache for that entity'), and the return value. The cache side effect is not derivable from annotations and is exactly the kind of mutation disclosure an agent needs.

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

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

Four tight sentences, each carrying distinct information (purpose, non-idempotency warning, return, cache effect, param guidance), with the core action front-loaded. 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 mutation tool with no output schema, the description covers the return value, the idempotency hazard, and a side effect, and the schema fully documents all four parameters. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds actionable semantics by tying enum_values to select-type fields in a usage instruction. It doesn't explain field_type values beyond what the schema already documents, keeping it slightly above baseline rather than maximal.

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 custom field') and enumerates the target scope (leads, contacts, or companies), which lets an agent distinguish it from read-oriented siblings like list_custom_fields at a glance.

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

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

Explicitly names the alternative ('check list_custom_fields first') and gives a conditional usage rule ('Provide enum_values for select-type fields'). Both the when-to-use and the prerequisite are stated, not inferred.

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 idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the description need not restate the safety profile. It still adds real context beyond the structured data: non-idempotency restated in plain terms, automatic tag creation as a side effect, and the return value despite no output schema.

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

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

Four short sentences, each carrying distinct information: creation semantics, idempotency, tag side effect, return value, and sibling routing. Front-loaded with the core purpose and 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?

Although no output schema exists, the description states that the created lead object is returned, and it covers the notable side effect (auto-created tags). For a single-entity create tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (including stage_id, pipeline_id and responsible_user_id) is already documented in the schema. The description only adds the tag auto-creation behavior, which is a side effect rather than parameter meaning. 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 one lead in Kommo') with the scope-limited singular cardinality, and explicitly distinguishes itself from create_lead_complex. An agent can tell it apart from the bulk/complex siblings without opening a schema.

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

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

Names the alternative create_lead_complex and the exact condition that selects it (when contact and company must be created in the same call). It stops short of stating exclusions such as when to prefer bulk operations, but the routing guidance is clear.

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 idempotentHint=false, readOnlyHint=false and openWorldHint=true, but the description goes further by explaining what that means (always creates new records, never links existing ones) and adds a non-obvious conditional: phone/email are only stored if the account has PHONE/EMAIL contact fields. It does not mention auth/permission requirements or error behavior, so not a full 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?

Four short sentences, front-loaded with what it does and the endpoint, followed by the most actionable caveat (non-idempotency) and the alternative. No redundancy or filler.

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

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

For an 8-parameter creation tool with no output schema, the description covers what it returns ('Returns the created lead'), the non-idempotent nature, the composite-creation semantics, and the fallback tool. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the account-level PHONE/EMAIL field prerequisite constrains when contact_phone/contact_email take effect, and the 'in one request' framing clarifies that company_name/contact_name create new records.

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 lead together with a new contact and/or company in one request') and even names the endpoint POST /leads/complex. It is immediately distinguishable from the sibling create_lead because it explicitly scopes the composite behavior.

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

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

Gives an explicit routing rule: 'Use create_lead if no contact or company is needed.' It also warns 'Not idempotent: always creates new records, never links existing ones,' telling the agent when this tool is the wrong choice for linking to existing contacts/companies.

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 idempotentHint=false, and the description reinforces this with the consequence ('each call creates another pipeline'), which is more actionable than the flag alone. It also discloses a novel side effect absent from the annotations: clearing the pipelines cache. Return value is described, partially compensating for the missing output schema.

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

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

Five short sentences, each carrying distinct information: creation semantics, idempotency, return value, follow-up step, and a side effect. The core action is front-loaded 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 simple single-param creation tool with no output schema, the description covers the important non-obvious behaviors: non-idempotence, the return value, the cache-clearing side effect, and the natural next step. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema. The description adds only the default sort order (99) as useful context but no format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new sales pipeline') and immediately distinguishes itself from sibling tools by naming create_stage as the follow-up step and implying the list_pipelines/update_pipeline relationship. An agent can identify the operation without inspecting 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?

Explicitly tells the agent to use create_stage afterwards to add stages, giving a clear workflow ordering that sibling names alone wouldn't convey. It stops short of stating when NOT to use it or naming a direct alternative for pipeline creation, so it falls short of a 5.

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

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

Annotations already declare idempotentHint=false and destructiveHint=false, but the description adds substantive behavior: stages are appended after existing editable stages with computed sort, each call creates a new record, the created stage is returned, and both stage and pipeline caches are cleared. That cache-invalidation side effect in particular is not visible in any structured field, making this genuinely additive.

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?

Five short sentences, each carrying distinct information: purpose, placement rules, idempotency, return value, and cache side effect. The core action is front-loaded and nothing is repeated for padding.

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

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

For a three-parameter creation tool with no output schema, the description covers the essential call-time concerns: placement, non-idempotency, return value, and cache invalidation. It could still mention permission requirements, whether stage names must be unique, or what happens on invalid pipeline_id, but the definition is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents name, color, and pipeline_id in detail (including where to obtain the ID and Kommo palette caveats). The description adds no parameter-specific detail beyond the schema, so the baseline 3 is appropriate.

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

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

The first sentence gives a specific verb and resource ('Add a stage to a pipeline'), so the operation is unambiguous. It does not explicitly differentiate from sibling tools such as create_pipeline or update_stage, but the purpose itself is clear enough that an agent can identify it without opening the schema.

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

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

Usage is implied rather than stated: the description explains placement and non-idempotency, which implicitly tells the agent this is for creating brand-new stages. It never names an alternative or a when-not condition (e.g., use update_stage to rename or reorder), so the agent must infer the boundary from the purpose 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?

Declares 'Not idempotent: each call creates a new task' and 'Returns the created task', adding critical context beyond the annotations (which already declare idempotentHint=false, readOnlyHint=false). This warns agents against retry duplication, a key behavioral trait. It doesn't address permissions, rate limits, or failure modes, keeping it short of 5.

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

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

Three compact sentences front-loading the action, non-idempotency warning, and routing advice. Every sentence earns its place with no redundancy.

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

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

Complete for a mutation tool with annotated safety profile and fully documented schema. It covers scope, side-effect behavior, return value, and sibling routing. No output schema needed since it states the return. Nothing an agent needs to call correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters fully. The description adds no parameter-level syntax or format details beyond what the schema provides. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb ('Create') and resource ('follow-up task (type 1) attached to a lead'), and distinguishes from sibling list_tasks. The '(type 1)' detail signals a specific task subtype, which no sibling covers.

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

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

Explicitly routes to list_tasks for review and add_note for non-actionable remarks, providing direct alternatives for the closest sibling tools. When-to-use is clear without needing to read other definitions.

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 real substance beyond them: the operation is a soft-delete implemented as PATCH /leads/{id} with is_deleted=true, and the lead disappears from normal lists. This tells the agent exactly what state change occurs and that it is not a hard removal.

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 mechanism, then effect, then prerequisite. Four short sentences, none wasted, each adding distinct information.

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

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

For a single-parameter delete tool with no output schema, the description covers the mechanism, the destructive effect, and the safety prerequisite. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so lead_id is already fully documented as an integer obtainable from list_leads/create_lead. The description reinforces the source of the id ('confirm with get_lead first') but adds no syntax or format detail beyond the schema — baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb ('Delete') and resource ('lead') and immediately clarifies the actual mechanism (PATCH is_deleted=true soft-delete vs a hard-delete call), which distinguishes it from mutation siblings like update_lead or move_lead_stage.

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

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

Gives a clear prerequisite — 'Confirm the lead_id with get_lead first' — which directs the agent to the right sibling for verification. It does not state explicit when-not conditions, but for a delete tool with no true alternative that is a minor gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only' adds little. It does add value by disclosing the return shape (embedded tags and custom_fields_values), which the annotations and lack of output schema do not cover.

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

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

Three short sentences, front-loaded with purpose, followed by safety note and return shape. No waste, no redundancy.

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

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

Covers purpose, lookup alternative, safety, and return fields for a one-parameter read tool. Without an output schema, the description could say more about the response envelope, but it gives enough for reliable invocation.

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

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

Schema description coverage is 100% and the contact_id description already explains its origin and type. The description's 'by ID' adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (one contact) and distinguishes from siblings by naming list_contacts as the lookup alternative. An agent can pick this tool 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?

Tells the agent to use list_contacts to find the ID, which is clear routing guidance. It doesn't state when not to use it (e.g., versus update_contact for reading-modifying), but the context is sufficient for a single-resource getter.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's 'Read-only' line is largely redundant. However, it adds real value by disclosing the return payload (full lead object with embedded contacts, tags, and custom_fields_values) in the absence of an output schema.

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

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

Three short sentences, front-loaded with the action, then the safety trait, then the return contents and the routing hint. 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 single-parameter read tool with no output schema, the definition covers safety, return contents, and alternative-tool routing. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema itself explains where to obtain the Kommo lead ID, so the schema carries the burden. The description adds only 'by ID', no format or edge-case detail beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one lead by ID') and immediately distinguishes itself from the sibling list_leads. An agent can route between get_lead and list_leads without inspecting either schema.

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

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

Explicitly names the alternative ('Use list_leads instead to browse or find lead IDs') and gives the condition that selects it, plus how to obtain the required ID. No inference required.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces read-only and adds that it returns template objects as provided by Kommo. It also clarifies the server's limitation (cannot send templates). This adds useful context beyond the annotations, though it doesn't cover rate limits 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?

Three concise sentences, front-loaded with the core action. Each sentence adds distinct value: purpose, safety, return format, and limitation/alternative. No wasted words.

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

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

For a parameterless, read-only list tool with rich annotations, the description is nearly complete. It explains what it returns and its limitation. The only missing piece is potential pagination or result size, but given no output schema and the simplicity, this is minor. Overall, it provides sufficient 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?

The tool has zero parameters, so there is nothing to parameterize. The description doesn't need to explain parameters, and the baseline for 0 params is 4, but the description correctly indicates no filtering or input is needed.

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

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

Clear verb+resource: 'List the account's chat message templates.' The description also distinguishes itself from sibling send_chat_message by stating this server only lists and cannot send. An agent can immediately understand the tool's function and boundaries.

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

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

Explicitly states the tool is read-only and cannot send templates, pointing to send_chat_message as the alternative for sending. It clarifies when to use this tool (to list) versus the sibling. No explicit when-not-to-use beyond that, but the context is clear.

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 new behavior beyond them: results are a single page, hard-capped at 100, with no cursor continuation, which tells the agent it cannot exhaustively enumerate companies with this tool.

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

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

Three short clauses, front-loaded with the verb and resource, and each carries information. Slightly redundant in re-stating the limit cap that the schema already documents, 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?

With no output schema, the description does the necessary work of telling the agent what comes back (company objects, one page only). Combined with annotations covering safety, an agent has enough to call this correctly, though company fields and whether a total count exists remain unstated.

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

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

Schema coverage is 100% and the single `limit` parameter is fully described in-schema, including the default 50 and cap of 100. The description only restates that cap, adding no syntax or semantic value beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List companies') and immediately bounds the result set ('one page of company objects'). It does not name or differentiate from siblings like list_leads/list_contacts, but the scope statement is precise enough that an agent knows exactly what it retrieves.

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

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

Explicitly rules out two usage modes an agent might otherwise assume: 'no name search and no further pagination'. That is a real when-not signal, though it stops short of naming an alternative tool for searching or paging.

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 read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns one page only, capped at `limit` (max 100), with no further pagination, which prevents an agent from assuming it can page through results. It omits auth requirements and rate limits, so it stops short of a 5.

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

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

Four short clauses, front-loaded with purpose, then return behavior, then parameter usage, then the sibling pointer. No sentence is wasted.

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

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

With no output schema, the description compensates by describing the return shape (contact objects) and the pagination limit. Combined with full schema coverage and read-only annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema (including the name/phone/email match and the 50 default/100 cap). The description largely restates those same facts rather than adding syntax or format detail, so the baseline 3 applies.

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

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

States specific verbs (search/list) and the resource (contacts), and explicitly distinguishes itself from get_contact for single-record retrieval. An agent can route between list_contacts and get_contact without opening either schema.

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

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

Gives explicit conditional guidance: pass `query` to match by name/phone/email, omit it to list recent contacts, and use get_contact for full details of one contact. Both the when-to-use and the alternative are named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them: a 1-hour cache and the shape of returned field objects (id, name, code, type, enum options). It stops short of describing cache invalidation or pagination behavior.

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

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

Four short sentences, front-loaded with what the tool does, then safety, return shape, caching, and the chaining hint. No sentence is redundant.

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

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

With no output schema, the description steps in to describe the returned object fields, and with only one optional parameter and full annotation coverage there is nothing an agent needs to call this correctly that is missing.

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

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

Schema coverage is 100% with a single, fully documented entity_type parameter including its default, so the schema does the heavy lifting. The description's mention of 'leads, contacts, or companies' merely restates it without adding format or edge-case detail, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (custom field definitions) and scopes it to the three entity types, which clearly separates it from create_custom_field and from the lead/contact CRUD siblings.

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

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

Gives concrete downstream guidance: use the returned field IDs in custom_fields_values when calling update_lead or update_contact. It does not state exclusions or when to prefer a sibling, but the intended workflow context is explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: the return shape (lead objects with embedded contacts and tags) and the pagination rule when limit exceeds 50.

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

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

Three tight sentences, front-loaded with purpose and filtering, then return shape, then the alternative. No filler and nothing overloaded.

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

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

With no output schema, the description usefully describes the returned array and its embedded contacts/tags, and covers pagination. Adequate for a simple zero-required-param list tool; only minor gaps around total-count/ordering behavior.

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

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

Schema description coverage is 100%, so the schema already documents limit, stage_id, and pipeline_id including the pipeline_id dependency for stage_id. The description only restates that results are capped at `limit`, adding little 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 and resource (list leads) plus scope (optional pipeline/stage filtering). It is immediately distinguishable from get_lead and the mutation siblings like create_lead/delete_lead.

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

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

Explicitly routes the agent to get_lead for custom fields of a single lead, which is a clear use-vs-use distinction. It lacks when-not guidance for other siblings (bulk_update_leads, list_contacts), so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior beyond them: a 10-minute cache and the caveat that recent changes may not appear. It also sketches the returned object shape (id, name, sort, embedded stages).

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

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

Three short sentences, front-loaded with the purpose, then behavior, then usage. Every sentence earns its place with no redundancy.

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

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

No output schema exists, yet the description compensates by naming the returned fields and embedded stages, plus the caching caveat and the downstream purpose of the IDs. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes no parameters, so the schema-dimension baseline is 4. The description does not need to explain any arguments, and it correctly focuses on scope and return content instead.

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 sales pipelines in the account') and clearly distinguishes itself from create_pipeline/update_pipeline siblings. It also frames its role as the entry point for obtaining pipeline_id/stage IDs used by other 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?

Gives explicit when-to-use guidance ('Start here to obtain the pipeline_id and stage IDs used by most lead tools'), which orients the agent within the tool family. It does not name an alternative or a when-not condition, but for a zero-param listing tool the routing context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavioral context the annotations lack: the return shape (id, name, sort, color, is_editable) and a 10-minute cache, which tells the agent results may be stale. It stops short of 5 by not saying whether the cache is invalidated after stage mutations.

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

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

Four short sentences, zero filler, and the purpose plus read-only nature are front-loaded ahead of the return shape, cache note, and downstream routing. Every sentence carries distinct 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 compensates by enumerating returned fields, and it adds caching behavior and downstream consumers. For a single-parameter read tool this leaves nothing an agent needs missing.

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

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

Schema description coverage is 100% and the single pipeline_id parameter is fully documented in the schema, including 'Obtain it from list_pipelines'. The description adds no format, range, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the stages (statuses) of one pipeline'), with the clarifying synonym 'statuses' and the scoping constraint 'one pipeline'. This cleanly separates it from sibling mutations like create_stage/update_stage and from list_pipelines.

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

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

Explicitly routes the agent downstream: 'Use the stage IDs with list_leads, create_lead, and move_lead_stage.' That is concrete when-to-use guidance tied to named siblings. It does not state any when-not-to-use or exclusion conditions, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: a 100-item result cap and the return shape (tag objects with id and name).

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

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

Four short sentences, each earning its place: purpose and limit, safety, return shape, and usage guidance. The most important information is front-loaded.

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

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

For a simple, low-complexity list tool with rich annotations and full schema coverage, the description is complete: it states purpose, scope, return shape, truncation limit, and when to use it. No output schema exists, and the description covers the essential return information.

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

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

Schema description coverage is 100%, and the sole entity_type parameter is fully documented in the schema with its default and path semantics. The description adds no parameter-level detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb (list), resource (tags), and scope (account, first 100), making the tool's purpose immediately clear. It also names the related sibling tools add_tag and remove_tag, so an agent can distinguish this listing tool from tag mutation tools without opening schemas.

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

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

It explicitly tells the agent to use this tool to check exact tag names before add_tag or remove_tag, providing clear context and alternatives. However, it does not state when not to use it (e.g., if tag names are already known), so it falls just short of the highest bar.

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 'Read-only' is redundant. The description earns credit by disclosing the return volume constraint ('one page of Kommo's default size, no pagination or limit parameter') and precisely defining 'overdue', both of which are absent from structured fields.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the constraints and definitions following. Every sentence carries information an agent needs.

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

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

For a two-parameter read-only list tool with no output schema, the description covers purpose, filter semantics, safety, and the otherwise-hidden pagination limitation. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description nonetheless sharpens filter_overdue beyond the schema's 'deadline has passed' by specifying 'at or before now and not completed', adding real semantic precision for the overdue predicate.

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 tasks') plus the two available scopes (one lead, overdue only). It is clear what the tool returns, though it does not explicitly contrast itself with siblings like create_task or the lead-listing tools, which are distinct enough that confusion is unlikely.

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?

Explains the two optional filters and the condition that selects each ('for one lead', 'only overdue ones'), so an agent knows when to set them. It does not name an alternative tool or state when not to use this one, but the usage context is clear.

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 it non-read-only, non-destructive, idempotent and open-world, so the safety profile is covered. The description adds the result shape ("Returns the updated lead") and the cross-pipeline condition, which is genuinely beyond the annotations; it stops short of stating failure behavior or what happens to other lead 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?

Three short sentences, front-loaded with the action and return value, then the alternative routing, then the conditional param note. No filler and no repetition that isn't doing routing work.

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

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

With no output schema, the description usefully states the return value, and all three parameters are fully documented. For a 3-param, non-destructive tool this is nearly complete; only error/edge-case behavior (invalid stage or cross-pipeline mismatch) is unaddressed.

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

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

Schema coverage is 100% and every schema description already explains its parameter, including the exact pipeline_id conditional that the description repeats. Baseline 3 applies since the description adds no syntax, format, or constraint 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 ("Move a lead to another stage") and names the mechanism (status_id, pipeline_id) plus the return value. It explicitly distinguishes itself from the sibling update_lead, so an agent can route correctly without opening schemas.

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

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

"Use this instead of update_lead for pipeline moves" names the alternative and the condition selecting it, and "Pass pipeline_id when moving to a stage in a different pipeline" gives the conditional trigger for the optional param. Explicit when-to-use plus alternative routing.

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

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

Goes well beyond the annotations: it explains the read-modify-write mechanism, that other tags are preserved, that the tag isn't deleted account-wide, and — critically — that a non-existent tag name gets created as a side effect. It also restates idempotency in concrete terms ('Safe to repeat') and discloses the return value.

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

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

Front-loaded with the core action, then four short clauses each adding distinct, non-redundant information (mechanism, preservation, side effect, return). No filler.

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

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

For a simple 2-param mutation with no output schema, the description covers mechanism, destructive scope, side effects, idempotency, and the return value. An agent has everything needed to call it correctly and predict its effects.

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

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

Schema coverage is already 100%, so the schema carries most weight, but the description adds a subtle semantic: 'by name' plus the side effect that a tag_name which does not exist is created. That clarifies how the tag_name param behaves in an edge case the schema doesn't mention.

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 (Detach) and resource (tag from a lead), and scopes it by name. It's clearly distinguishable from siblings like add_tag, list_tags, and delete_lead without opening any schema.

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

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

The usage context is implied rather than stated — an agent can infer this is the inverse of add_tag, but the description never names alternatives or gives explicit when-to-use/when-not conditions. 'Safe to repeat' hints at idempotent retry usage but no exclusion guidance 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 readOnlyHint=false and idempotentHint=false, but the description adds concrete consequences beyond that: the message is delivered externally, cannot be recalled by this server, and repeated calls produce duplicates. It also discloses a specific failure path (error when the lead has no conversation), which the annotations do not convey.

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

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

Three short sentences, front-loaded with the core action, then the lookup rule, the safety implications, and the alternative. Every sentence earns its place and no padding is present.

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

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

With no output schema, the description carries the right information: what it does, what requirement must hold, what side effects occur, and which sibling to use instead. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including that lead_id must come from list_leads. The description adds only indirect context ('first conversation linked to the lead'), not new per-parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Send an outgoing chat message to the customer in a lead's conversation') and immediately distinguishes itself from the sibling add_note. An agent can tell this apart from internal note-taking tools without opening any schema.

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

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

Explicitly routes the agent: use this for outgoing customer-facing messages, use add_note for internal notes. It also names the precondition (the lead must already have a linked conversation) and the failure mode when that precondition is unmet.

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-destructive, idempotent, open-world behavior, so the bar is lower. The description still adds genuine value with merge semantics ('Provided values overwrite existing ones; omitted fields are untouched') and return behavior. It doesn't cover error cases 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?

Three tight sentences, front-loaded with purpose, then return value, then mutation semantics. No filler, every clause 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?

For a 2-parameter mutation with no output schema, the description covers the operation, the return shape, and overwrite behavior, while annotations handle the safety profile. Minor gaps remain around error handling and custom-field specifics, but nothing essential for 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%, and the schema itself thoroughly documents both contact_id and the nested fields object. The description only restates that fields is sent as the body, adding little 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?

States a specific verb (update) and resource (contact) plus the exact mechanism (Kommo API v4 PATCH /contacts/{id}). This cleanly distinguishes it from siblings like create_contact, get_contact, and list_contacts without needing their schemas.

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

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

The phrase 'existing contact' clearly scopes it against create_contact, giving usable context for selection. It stops short of naming an alternative or stating explicit exclusions, so it lands just below the top tier.

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

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

Annotations already declare this is a non-destructive, idempotent write (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds the key PATCH semantic that only supplied values are overwritten and omitted fields are untouched, plus the return value. It does not mention permission requirements or rate limits, but the annotation bar is already met.

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

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

Three sentences, no padding: mechanism first, then destructive/merge semantics, then sibling routing. Every sentence carries distinct information.

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

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

For a two-parameter mutation tool the description covers mechanism, merge behavior, return value, and alternatives. Nothing needed to invoke it correctly is missing, and the absent output schema is compensated by the explicit 'Returns the updated lead'.

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

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

Schema description coverage is 100%, including a thorough `fields` description with common keys and an example, so the baseline is 3. The description's contribution is restating that `fields` is passed through as the PATCH body, which mostly duplicates what the schema already says.

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

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

States a specific verb (Update) and resource (existing lead), and pins down the exact mechanism (fields sent as the body of a Kommo API v4 PATCH /leads/{id}). It can be told apart from move_lead_stage and bulk_update_leads without opening a schema.

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

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

Explicitly routes the agent: use move_lead_stage for stage changes and bulk_update_leads for multiple leads. This is a genuine when-to-use/when-not-to-use statement naming the alternatives.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so 'Safe to repeat' is largely redundant. However, the description adds genuinely new behavioral context with 'Clears the pipelines cache' and 'Returns the updated pipeline,' disclosing a side effect and return behavior the annotations do not cover.

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

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

Four short sentences, front-loaded with the core action and scope before the side effect and the alternative. Every sentence carries information, though 'Safe to repeat' restates idempotentHint and could be trimmed.

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

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

For a two-parameter mutation tool with full schema coverage, annotations, and a stated return value, the description is nearly complete. No output schema exists, so restating 'Returns the updated pipeline' is useful, and the cache-clearing side effect is disclosed.

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

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

With 100% schema description coverage, both parameters are already documented (including the provenance note for pipeline_id). The description reinforces that name is the only mutable field, but adds no format or syntactic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (rename an existing pipeline) and immediately bounds the scope: 'Only the name can be changed with this tool.' It also names the sibling that handles the other mutation case, so an agent can distinguish it from update_stage without reading either schema.

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

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

Explicitly routes stage changes to update_stage, which is clear alternative guidance. It does not spell out when-not beyond that single case (e.g. creating vs updating), but the rename-only scope makes the boundary 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 cover safety (readOnly=false, idempotent=true, destructive=false), but description adds non-annotation context: partial updates only send provided fields, returns the updated stage, and clears stage/pipeline caches. That cache-invalidation and partial-update behavior is genuinely additive beyond 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-loads the purpose and mutation fields, then the requirement, return value, idempotency, cache effect, and ID source in tight, waste-free 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?

Covers purpose, partial-update requirement, return value, idempotency, cache side effect, and ID acquisition despite no output schema. Minor gap: no error case if an invalid stage_id is passed, but the definition is otherwise complete for a small mutation tool.

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

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

Schema coverage is 100% and already documents each parameter's meaning. The description adds only the partial-update constraint (at least one of name/sort/color), which is useful but the schema already carries the per-parameter detail; baseline 3 matches schema doing the heavy lifting.

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

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

States a specific verb (Change) and resource (a stage) plus the exact mutable fields (name, sort order, color). Distinguishes from sibling update_pipeline/update_lead by naming the stage entity and its unique attributes.

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

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

Explicitly says at least one of name/sort/color must be supplied and routes ID retrieval to list_stages. Does not name which sibling to use instead, but the 'Get IDs from list_stages' dependency is clear context.

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