callingly

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

Beyond the destructiveHint=false annotation, it adds meaningful behavior: the note is attached to the timeline, attributed to the authenticated user, and synced to connected CRMs. These are real side effects an agent should know.

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, no filler; the core operation is front-loadedentukan and each subsequent sentence adds a distinct fact. Excellent efficiency.

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 low-complexity, non-destructive action, the description explains the target, identification method, attribution, and sync side effects. It doesn't describe return/error details, but there is no output schema to clarify anyway.

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 high; the description mostly restates the lookup alternatives already present in the parameter docs. It doesn't add new meaning to the content parameter beyond what the schema says.

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

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

The description clearly names the operation ('Add a note'), the target ('a lead's timeline'), and the lookup options (lead_id or phone_number). It is specific enough to distinguish from sibling tools like add_tag, though it does not explicitly name the alternatives.

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

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

It explains how to identify the lead, which is helpful, but it gives no guidance on when to prefer this over siblings like add_tag, add_to_sequence, or schedule_sms, nor any exclusions or 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 provide idempotentHint=true and destructiveHint=false. The description adds meaningful non-obvious behavior beyond those hints: missing tags are created automatically, duplicate tagging is a no-op, and connected CRMs are kept in sync. No contradiction with 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?

Three sentences, all informative: the action, identification method, auto-creation behavior, idempotency, and integration side-effect. Front-loaded and free of 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?

Good for the common case, but it never explicitly states that exactly one of lead_id or phone_number is required, and it does not describe the outcome if neither is provided. Since only tag is marked required in the schema, this ambiguity is a real completeness gap despite the description saying 'Provide this or...'.

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%; each parameter already has a descriptive comment. The description adds the high-level relationship between lead_id and phone_number (one-or-the-other identification) but does not add much 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 opens with a clear verb and object ('Tag a lead by tag name'), then explains how to identify the lead via lead_id or phone_number. It does not explicitly contrast with sibling tools like remove_tag or add_note, but the operation 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?

The description gives clear operational context (which parameters to use, that unknown tags are auto-created, that duplicate tagging is a no-op), but it does not explicitly distinguish when to use this tool versus alternatives. No mention of remove_tag or when not to use this action.

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

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

Annotations already provide destructiveHint: true. Description adds that Callingly handles calls, texts, retries, and timing, which is behavioral context beyond the annotation. However, it doesn't disclose potential side effects like lead removal from other sequences or required permissions.

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

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

Two sentences: first defines action, second adds context. No wasted words, front-loaded with key information. Highly efficient.

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

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

For a tool with 7 parameters and no output schema, the description gives a high-level understanding but omits prerequisities (e.g., team existence, lead duplication handling) and results of the operation. It's 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 coverage is 100%, so parameters are fully described in the schema. The description does not add any additional meaning or usage notes for individual parameters, so 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?

Description clearly states 'Add a lead to a team's automated follow-up sequence' and distinguishes from siblings like 'make_ai_call' and 'send_sms' by contrasting with 'rather than a single call'. It's a specific verb+resource with 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?

Explicitly says 'Use this to start a persistent follow-up cadence rather than a single call', which implies when to use. It could explicitly state when not to use (e.g., for immediate calls use sibling tools), but provides clear 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 indicate readOnlyHint=true (safe read). The description adds value by detailing the exact data returned (custom fields, recent notes, etc.) and the two lookup methods, going beyond what annotations provide.

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

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

Two efficient sentences. The first sentence front-loads the action and output; the second covers parameters. Slightly verbose with listing all fields, but overall concise and well-structured.

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 tool with two optional parameters and no output schema, the description adequately explains what it does, what it returns, and how to identify the lead. Lacks mention of behavior when both identifiers are provided, but otherwise complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description reiterates the identification options but adds minimal new semantic meaning beyond the schema.

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

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

The description clearly states 'Read a lead's full profile' using a specific verb and resource, and explicitly lists the fields returned (name, phone, email, etc.), distinguishing it from sibling tools like update_lead or add_note.

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

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

The phrase 'so your AI and CRM stay in sync' implies when to use (for synchronization), and the description provides clear identification methods (by lead_id or phone_number), but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint=true. Description adds info on return data and filters, but doesn't disclose additional behavioral traits like rate limits or pagination beyond schema.

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

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

Two sentences, front-loaded with purpose, no redundancy, every sentence adds value.

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

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

Describes return fields, filtering options, and purpose. Lacks pagination details but limit parameter covers that. Overall adequate for a read tool with simple parameters.

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 covers parameter details (100% coverage). Description adds practical usage guidance (e.g., 'filter by lead_id to see how a specific lead's calls went'), going beyond schema definitions.

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

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

Description clearly states 'Read recordings, transcripts and outcomes of recent calls', specifies return fields, and distinguishes tool from siblings that are write/action oriented.

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?

Implicitly indicates usage for reading call data to sync AI/CRM, and filters are clearly explained. Could be more explicit about 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 indicate destructive behavior (destructiveHint=true). The description adds value by explaining the AI agent's actions (qualifies, answers questions, warm-transfers). No contradiction; the description does not need to repeat the annotation.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds necessary context. 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?

Despite no output schema, the description explains the full workflow (AI agent calls, qualifies, warm-transfers) and includes prerequisites. For a tool with 7 parameters, this is comprehensive.

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 parameters are already well-documented. The description adds no additional semantic detail beyond what is in the schema (e.g., phone_number format is already in 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?

The description clearly states the action: 'Make a call to a lead with an AI voice agent.' It specifies the verb (make), resource (call), and context (AI voice agent, qualification). It distinguishes from siblings like 'make_dispatch_call' and 'schedule_call' by focusing on automated qualification.

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 clear usage context: 'Use this to qualify a lead automatically before a rep gets involved' and includes a prerequisite ('The team must have an AI agent configured'). It does not explicitly state when not to use or name alternatives, 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?

Description details the process: rings sales rep(s), plays lead details, bridges to lead. Adds context beyond destructiveHint annotation. No contradictions.

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: purpose, process, usage guidance. Front-loaded with core action. No unnecessary text.

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

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

Covers purpose, process, and usage well. Lacks mention of return values or error states, but without output schema this is acceptable for a simple action 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%, so baseline is 3. Description adds no additional parameter information beyond schema, which is acceptable.

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

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

Description clearly states the tool makes a dispatch call to a lead via a human rep, distinguishes from siblings like make_ai_call by emphasizing human involvement and immediate action.

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 'use this for speed-to-lead when a lead should be contacted by a human right now', providing clear guidance on when to use. Does not explicitly name alternatives but implies them.

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 indicate readOnlyHint=true, and the description adds context about the returned metrics (call volume, connection rate, etc.). No contradiction. It discloses the scope (account-level, date range) and what data is included.

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

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

The description is two sentences, front-loaded with the action and scope. Every sentence adds value with 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 query tool with 3 optional parameters and no output schema, the description lists key return metrics (call volume, per-rep performance) sufficiently for an agent to understand what it provides. Minor gap: no mention of pagination or data limits, but overall complete enough.

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 parameters have descriptions. The tool description does not add extra meaning beyond the schema's parameter descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool queries call reports over a date range and lists specific metrics like call volume and per-rep performance. It distinguishes from sibling tools that are action-oriented (making calls, sending SMS).

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 concrete example questions like 'how many leads did we reach last week', guiding the agent on appropriate use cases. It does not explicitly state when not to use it or mention alternatives, 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?

The description explicitly states that removing a non-existent tag is a no-op, which adds behavior beyond the idempotentHint annotation. The annotations already cover idempotency and non-destructiveness, but the description reinforces and clarifies this, adding 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?

The description is two sentences, concise and front-loaded with the primary purpose. It includes the important no-op caveat without extraneous detail. It could be slightly more structured but is efficient.

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

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

The description covers the core action and the no-op behavior, essential for any lead with or without the tag. However, it does not detail prerequisites (e.g., whether the lead must exist) or any side effects beyond the no-op. The output is likely void, so return format isn't critical. Adequate for a simple 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?

The input schema already has 100% coverage for all three parameters. The description does not add extra meaning beyond the schema—it simply restates that identifiers can be lead_id or phone_number, which is already in 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?

The description clearly states the action (remove a tag), the target (a lead), and the identifier options (lead_id or phone_number). It is specific enough to distinguish from sibling 'add_tag' and other lead operations, though it doesn't explicitly name a 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 implies when to use it (removing tags from leads) but does not provide explicit guidance on when not to use it or mention alternatives like 'add_tag'. The no-op behavior for missing tags is a useful usage note but not a full comparison with 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 include destructiveHint: true, but description does not address destructive behavior. Description adds positive details about dialing, reminders, retries, which is useful but doesn't fully explain side effects. No annotation contradiction.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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

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

Missing explanation of return value (e.g., whether it returns a call ID). No output schema provided. Also lacks error cases or prerequisites. Acceptable for a simple tool but incomplete.

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

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

Schema covers all 8 parameters with descriptions. Description adds valuable context: E.164 format for phone_number, timezone-dependent string format for scheduled_at, and example values. Greatly aids correct parameter entry.

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?

Clearly states the tool schedules a callback instead of immediate calling, with specific verb 'schedule'. Distinguishes from sibling tools like schedule_sms and make_ai_call by focusing on callbacks.

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 'Use this to book a callback for later', providing clear usage context. Does not explicitly list alternatives or when not to use, but implies contrast with immediate calling.

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

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

The description discloses that messages are 'rendered and sent' at the scheduled time, and notes that 'past times are bumped to now.' This adds important behavioral context beyond the 'destructiveHint: true' annotation, which only indicates side effects.

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

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

The description is two sentences long, front-loads the core purpose, and wastes no words. Every sentence adds value.

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

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

The description covers the main purpose and usage but does not explain what the function returns (no output schema). It also omits details like whether scheduling can be edited or cancelled. Given the tool's simplicity, 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. The description does not add new meaning beyond what the schema already provides for each parameter.

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

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

The description clearly states the verb ('schedule'), resource ('SMS text message'), and key differentiator ('at a future time instead of sending immediately'). It distinguishes from the sibling tool 'send_sms' which likely sends immediately.

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 explicitly provides a use case: 'time a reminder or follow-up to the lead's timezone.' It also implies when not to use it (immediate sending) via the phrase 'instead of sending immediately.' However, it does not explicitly name alternatives like 'send_sms'.

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 indicate destructiveHint=true, and the description aligns by stating 'send' (a write operation). It adds useful prerequisites (lead existence, must use own number). No contradictions.

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

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

Two sentences that front-load the core action and constraints, followed by usage examples. 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?

Given the tool's simplicity (3 parameters, no output schema) and the presence of annotations, the description adequately covers purpose, prerequisites, and usage scenarios. Missing details like return values or error handling are acceptable for this type of 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?

The input schema has 100% description coverage, so the description adds little beyond what the schema already provides. 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 clearly states the action (send an SMS), the target resource (existing lead), and the source (your Callingly numbers). It also provides example use cases, making the purpose unmistakable.

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

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

The description explicitly says when to use the tool ('introduce an agent, confirm a callback, or follow up') and includes a prerequisite (lead must exist). It does not mention when not to use or alternatives, 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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: partial updates only, the lead can be identified by either lead_id or phone_number, and custom field slugs not defined on the account are ignored and reported back. This goes beyond the annotations and helps the agent predict side effects.

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

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

Three sentences with no waste. The core action and field list are front-loaded, the identification and partial-update semantics come next, and the sibling routing is at the end. 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 10-parameter tool with no output schema, the description covers the essential invocation semantics: what fields can be updated, how to identify the lead, partial-update behavior, and how to route to siblings. It doesn't describe the return value, but with no output schema and idempotentHint=true, that's a minor gap. The custom_fields behavior is well explained.

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 explaining the partial-update behavior, the lead_id-or-phone_number identification requirement, and the custom_fields behavior (ignored/reported back). It also tells the agent to call get_lead to discover available slugs, which is genuinely useful parameter-level 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 states a specific verb ('Update') and resource ('a lead's profile fields'), enumerates the exact fields, and explicitly distinguishes itself from sibling tools like update_stage and add_tag/remove_tag. An agent can tell exactly what this tool does and what it does not do.

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 explicitly says when to use this tool ('To change the lead's stage use update_stage; to manage tags use add_tag / remove_tag') and provides identification guidance ('Identify the lead by lead_id or phone_number'). It also clarifies partial-update semantics ('Only the fields you provide are changed'), which is critical for correct invocation.

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

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

The description adds the prerequisite that the stage must exist and discloses the side effect that the change syncs to connected CRMs, going beyond the idempotentHint and destructiveHint annotations. It is slightly light on failure behavior but sufficient for this simple mutation.

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 and identifier options, with no filler or repeated schema text.

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

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

For a simple three-parameter tool, the description covers the prerequisite, identifier choice, and downstream side effect. It does not specify behavior when both identifiers are provided, but that is a minor edge case.

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 description does not need to re-explain each parameter. It adds a small amount of context about the stage-must-exist requirement and the identifier alternatives, but the schema already carries the core semantics.

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

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

The description opens with a specific verb and resource: 'Move a lead to a pipeline stage by stage name.' It clearly identifies the operation and the two accepted lead identifiers, making the tool's purpose unambiguous and distinct from siblings like get_lead or update_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?

It gives clear invocation guidance: use the stage name, the stage must already exist, and the lead is identified by lead_id or phone_number. It does not explicitly contrast with update_lead, but the usage context is clear enough.

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