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

Without annotations, the description discloses important behavioral traits: the structure of field_values, handling of custom fields via internal names, phone country code requirement, and email/phone type conventions. Missing details on error handling or side effects but still strong.

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 long but well-structured: high-level purpose, then prerequisites, then detailed field instructions. Each sentence adds value, though some details (e.g., email/phone types) could be more compact. Mostly earns its length.

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 complexity (mutation tool, no annotations, one parameter with 0% schema coverage, nested objects), the description is remarkably complete. It covers prerequisites, field structures, edge cases, and references to other tools. Output schema exists, so return value details are not needed.

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 only parameter field_values is a freeform object with 0% schema description coverage. The description adds extensive meaning: how to structure standard fields, custom fields, emails, phones, picklists, and dates. This far exceeds the schema's minimal definition.

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

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

The description clearly states 'Create a lead in Kylas CRM' with a specific verb and resource. It also notes the flexible field approach, distinguishing it from sibling tools like 'update_lead' or 'search_leads'.

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 explicit prerequisites: 'You MUST call get_lead_field_instructions FIRST'. It also gives conditions to avoid calling (e.g., if phone country code is missing, ask user) and context on when to infer fields.

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?

Since no annotations are provided, the description carries full burden. It discloses the tool is read-only and returns profile fields including timezone, recordActions, name, etc. It does not mention destructive behavior or side effects, which is appropriate. The description is transparent about the return value and its usage.

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 well-structured with a clear main sentence followed by bullet-point usage guidelines. It is fairly long but every sentence adds value. Slight improvement could be more concise grouping, but overall effective.

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

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

Given no parameters, an output schema exists, and the description thoroughly covers when and how to use the tool, it is fully complete. It provides all necessary context for an AI agent to correctly invoke and use the output.

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 0 parameters, the baseline is 4. The description does not need to add parameter info, and it provides context on what the tool returns, which is sufficient.

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 explicitly states the tool's purpose: 'Get the current authenticated user's profile from Kylas (GET /users/me).' It clearly identifies the resource and action, distinguishing it from sibling tools by focusing on the returned timezone and profile fields.

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 explicit guidance: 'Call this whenever a date or datetime-related query is involved.' It then gives specific instructions for using the returned timezone in filtering (search_leads, search_idle_leads) and lead creation (create_lead), effectively telling when and how to use this tool versus alternatives.

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

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

No annotations provided; description implies read-only behavior through 'Get full details' but does not explicitly state absence of side effects, auth requirements, or rate limits. Adequate for a simple read operation.

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

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

Two concise sentences plus a parameter line. No wasted words, front-loaded with main purpose.

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

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

Output schema exists, so return value explanation is unnecessary. Description covers purpose, usage, and parameter source. No annotation gaps, but missing explicit behavioral transparency. Still complete for a simple getter.

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

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

Input schema has one parameter (lead_id) with no description. Description adds meaningful context: 'The lead ID (e.g. from search_leads or search_leads_by_term results).' This clarifies the source of the ID. Since schema coverage is 0%, description compensates well.

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 'Get full details of a lead by ID' and specifies the REST endpoint. Distinguishes from sibling search 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?

Explicitly says 'Use when the user asks for complete lead info, lead details, or to view a specific lead.' Provides positive guidance but does not list alternative tools for when not to use.

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

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

No annotations provided, so description carries full burden. It explains that the tool returns a 'cheat sheet' with specific data types (API names, Field IDs, Picklist Option IDs). This is sufficient for a read-only tool with no parameters, though it could mention idempotency or lack of 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?

Four sentences, each delivering distinct value: action, ordering, output detail, usage. Front-loaded with primary purpose. 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 zero parameters, existence of output schema, and sibling tools including create_lead, description fully covers what an agent needs: what it does, why call it first, what it returns, and how to use the result. No gaps.

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

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

Input schema has zero parameters (schema coverage 100%). Baseline is 4 as per instructions. No parameter info needed in description; it correctly omits any.

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 verb 'Get', resource 'all lead fields', and scope 'current tenant'. Distinguishes from siblings like create_lead, search_leads by emphasizing it is a preliminary step.

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 instructs 'CALL THIS FIRST before creating a lead' and 'Use this to build field_values for create_lead'. Also advises 'do not use static fields', providing clear when-to-use and how-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It implies a read operation via GET and mentions response fields, which is good. However, it could explicitly state idempotency or that the tool is safe to call multiple times without side effects. Still, the intent is clear enough.

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 efficient: it starts with the core purpose, then gives usage context, and ends with parameter guidance. Every sentence contributes to understanding without 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?

Given that an output schema exists (not shown but referenced), the description need not detail return values. It already mentions key fields. For the intended workflow (fetch reasons, select one, update lead), the description is completely sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining that pipeline_id comes from the lead's current pipeline or from lookup_pipelines, providing practical context for using the parameter. This adds significant value beyond the schema.

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

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

The description clearly states the tool returns full pipeline details (stages, unqualifiedReasons, lostReasons) by ID, with the HTTP method. This distinguishes it from sibling tools like get_pipeline_stages or lookup_pipelines by specifying exactly what data is returned.

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

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

The description explicitly tells when to call this tool ('when moving a lead to Closed Lost or Closed Unqualified'), how to use the result (present reasons to user, ask for a pick), and the follow-up action (call update_lead with the exact string). This is comprehensive guidance.

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

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

Fully describes return values (pipeline name, list of stages with id, name, forecastingType) and constraints. With no annotations, this is sufficient.

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?

Every sentence serves a purpose: purpose, usage guidance, return format, parameter description. No wasted words, front-loaded with key 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?

Given one parameter and existing output schema, the description covers all needed context: preconditions, return structure, and downstream usage. Complete for an agent to use 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?

With 0% schema description coverage, the description explains pipeline_id as 'The pipeline ID (from lookup_pipelines)', adding crucial context beyond the schema's type-only definition.

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

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

Clearly states 'Get stages for a pipeline' with specific verb and resource. Distinguishes from siblings like lookup_pipelines and search_leads.

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 instructs to call only after pipeline confirmation from lookup_pipelines, and provides detailed guidance on using stage IDs in search_leads and handling ambiguities.

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

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

No annotations provided, so description carries full burden. It describes the lookup behavior and workflow, but does not explicitly state that it is read-only or mention authorization needs. However, the context (lookup) implies read-only.

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

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

Well-structured: purpose, usage guidelines, parameter details. Slightly verbose but every sentence adds value. Could be slightly more concise, but is clear and organized.

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 annotations or output schema details, but description covers the essential workflow. Sibling tools are listed, and the tool's role is clear. Missing some details like permissions or error cases, but sufficient for basic use.

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

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

Despite 0% schema coverage, the description details all four parameters: query (format and behavior), entity_type (default LEAD), page (0-based), size (max 50). This fully compensates for missing schema descriptions.

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

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

The description clearly states 'Look up pipelines by name (for leads)' and specifies when to use it: 'when the user asks for leads by stage but does not specify which pipeline.' It distinguishes itself from sibling tools like get_pipeline_stages.

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?

Explicit step-by-step instructions: 'Call this first; do NOT call get_pipeline_stages until after the user confirms.' Describes when to call and what to do with results (present, ask confirmation).

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

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

No annotations provided, so description carries full burden. It does not disclose authentication, rate limits, or error handling. It mentions server behavior (sending name:value) but lacks deeper behavioral traits. Output schema may cover return values, but overall transparency is moderate.

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

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

Well-structured with bullet points and clear separation of usage and parameter details. Slightly verbose but each sentence adds value. Could be trimmed slightly but maintains clarity.

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 3 parameters, no annotations, and presence of output schema, description covers usage workflow and parameter constraints comprehensively. Does not discuss output format but output schema likely handles that. Adequately 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 0%, but description compensates well. Explains query parameter format ('name:<product_name>' or plain name), and clarifies page/size defaults and bounds. Adds meaning beyond 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?

Description clearly states 'Look up products by name.' It provides a specific verb and resource, and distinguishes from sibling tools like search_leads by indicating it's a precursor to filtering leads by product.

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 when to use: 'Use this BEFORE filtering leads by product when the user gives a product name.' Provides clear guidance on handling single vs multiple results and how to proceed with search_leads calls.

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

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

No annotations provided, so description carries full burden. It discloses pagination behavior, cap of 500 for return_all, and parameter interactions. Could mention error conditions or rate limits, but still strong.

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?

Concise with no wasted words. Front-loaded purpose, then bullet-point parameter details. Two sentences cover behavior and cross-reference.

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 complexity and existence of an output schema, the description fully covers input behavior, pagination, limits, and cross-tool usage. No gaps.

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

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

Schema coverage is 0%, so description must compensate. It explains each parameter: query format (e.g., 'firstName:last'), page as 0-based, size max 50, return_all behavior. Adds significant value beyond 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 'Look up users by name, or list all users in the system.' This is a specific verb and resource, and it distinguishes this tool from siblings which deal with leads, pipelines, etc.

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

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

Provides explicit guidance on when to use return_all=True, how to format the query, and even cross-references search_leads for the user ID. This helps the agent decide when to use this tool vs alternatives.

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

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

No annotations are provided, so the description bears full responsibility. It describes the tool as a pure datetime parsing and conversion utility with no side effects. However, it does not explicitly state that it is non-destructive or has no side effects. The example implies a stateless operation, which is sufficient but could be more explicit.

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 well-structured with the main purpose in the first sentence, followed by usage guidance, example, and parameter details. It is slightly verbose due to the example, but every sentence adds value. The example is helpful for an agent to understand the expected input format.

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 has an output schema (though not shown), the description explains the output as 'return UTC ISO string'. It covers the workflow dependency (calling get_current_user first), input format, and integration with create_lead. For a simple parsing tool, this is complete and leaves no gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It does so effectively: 'local_datetime: Datetime as the user said it (e.g. "11 Feb 2026 7:30 AM", "11th Feb 2026 at 7:30 am").' and 'timezone: IANA timezone from get_current_user (e.g. Asia/Calcutta).' This adds critical meaning beyond the schema's type-only 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?

The description clearly states the tool's purpose: 'Parse a datetime string in the user's timezone and return UTC ISO string for the Kylas API.' It specifies the action (parse), resource (datetime string), and output (UTC ISO string). It is distinct from sibling tools like create_lead and get_current_user by showing its specific role in the workflow.

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 instructs to 'Call get_current_user first to get the user's timezone' and provides an example workflow. It also states where the result is used: 'Use the returned string in create_lead field_values for date/datetime fields.' This gives clear when-to-use and dependencies, effectively guiding the agent.

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

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

No annotations are provided, so the description carries the full burden. It discloses the behavioral nuance of using both updatedAt and latestActivityCreatedAt, enforcing that both must be before the threshold. It also mentions pagination defaults. Missing are any authentication needs or error behavior, but the core behavior is well explained.

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 concise—just a few sentences—with no wasted words. It front-loads the purpose and then efficiently explains the dual-date logic and each parameter. 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 search tool with an output schema, the description covers all parameters, explains the selection logic, and provides defaults. It is complete enough for an agent to correctly invoke the tool without additional context.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaning for all parameters: days with usage example, time_zone with default and example, page with '0-based', size with max 100 and default, and sort with default value. This adds significant value beyond the bare 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 the verb 'Search' and the resource 'idle/stagnant leads'. It explains the precise logic using both updatedAt and latestActivityCreatedAt. This distinguishes it from sibling tools like search_leads and search_leads_by_term which search by other criteria.

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 'Search for idle/stagnant leads: no activity for at least the given number of days', providing clear when-to-use context. It explains the dual-date condition but does not explicitly state when not to use or mention alternatives. However, the context is sufficient for an agent to understand when to select this tool over siblings.

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

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

No annotations are provided, so the description carries the full burden. It does not explicitly state that the operation is read-only, but it is implied by 'search'. The description does not disclose potential side effects, rate limits, or response size constraints. It does, however, thoroughly explain the filter constraints and special cases, which adds some transparency but omits behavioral aspects like data freshness or timeout behavior.

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

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

The description is lengthy but well-structured with clear sections and examples. It is front-loaded with the main purpose and prerequisites. While some repetition exists (e.g., multiple 'call...first' patterns), the complexity of the tool justifies the length. The bullet-point formatting aids readability.

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 complexity (4 parameters, nested filter objects, high parameter logic), the description is extremely comprehensive. It covers all filtering variations, special handling for different field types, and pagination. No critical input aspect is missing. Since an output schema exists, the description does not need to explain return values. The description fully contextualizes the tool's usage.

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 0% description coverage, so the description must compensate entirely. It does so excellently by explaining each parameter in depth: the filters array structure, field types, operators, special cases for dates, picklists, user lookups, products, and pipelines. It also covers pagination and sorting defaults. This goes far beyond what the schema provides, enabling the agent to use the tool correctly.

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

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

The description clearly states the tool's purpose: 'Search/filter leads.' However, it does not distinguish this tool from sibling tools like search_leads_by_term or search_idle_leads, which are likely more specialized. The lack of differentiation prevents the agent from knowing when to use this tool over alternatives.

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

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

The description provides detailed step-by-step instructions for constructing filters (e.g., calling get_lead_field_instructions first, special handling for user lookups, pipelines, etc.), but it offers no guidance on when to use this tool vs. other search tools. There is no mention of scenarios where this tool is appropriate or inappropriate compared to alternatives, leaving the agent without comparative 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?

No annotations provided, so description carries full burden. It does not disclose behavioral traits like case sensitivity, search behavior (exact match, fuzzy), or what happens on no results. Lacks authorization or rate limit info. Minimal transparency beyond basic operation.

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

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

Description is well-structured, starting with purpose, then usage guideline, then parameter details. Not overly long, but some repetition (defaults stated twice). Every sentence adds value. Could be slightly more concise.

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

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

Given output schema exists (not shown), return values are covered. Complexity moderate with 4 params. Description covers parameter meanings and usage context but lacks behavioral details (case sensitivity, pagination behavior beyond defaults). Adequate but not fully complete.

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

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

Schema description coverage is 0%, but the description adds meaning for all 4 parameters: search_term with examples, page as 0-based, size with max, and sort with format example. Provides defaults and constraints. Could mention sortable fields but is still helpful.

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 'Search leads by a single term across multiple fields', specifying the verb, resource, and scope. It distinguishes from sibling tool 'search_leads' which filters by specific field, so purpose is distinct and precise.

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 when to use: when user asks for 'leads with X', 'leads containing Y', 'leads named Z' without field specification. Also explicitly directs to search_leads for specific field filtering. Excellent guidance with a clear alternative.

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

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

No annotations provided, so the description fully handles transparency. It explains the fetch-merge-PUT pattern, that other fields are left unchanged, and provides details on field handling. It could mention that this is a mutation (update) but the action itself implies it.

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

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

The description is well-structured: start with high-level purpose, then details on prerequisites and parameters. Each sentence adds value, though slightly dense. Not overly verbose.

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 two parameters, no annotations, and an existing output schema, the description covers the main aspects: what the tool does, how it works, parameter details, prerequisites, and special cases. It is comprehensive and leaves little ambiguity.

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

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

Schema coverage is 0%, so the description must explain parameters. It provides detailed meaning for lead_id (source e.g., search_leads) and field_values (format, examples like phone with country code, custom fields, picklists). This adds significant value beyond the bare 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 the tool updates a lead in Kylas CRM, using precise verbs ('Update') and specifying the resource ('lead'). It distinguishes itself from siblings like create_lead (create vs. update) and get_lead (read vs. write).

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 explicit prerequisites (call get_lead_field_instructions first, for owner use lookup_users) and references create_lead for field format. It does not explicitly state when not to use it, but the context is clear enough. Lacks explicit exclusions.

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