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

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing: no mention of permissions, duplicate detection, what happens on name collision, or what is returned on success. The verb 'Create' at least signals a mutation, but nothing beyond that.

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 single sentence is front-loaded and free of padding, which is good structure. But at this length for a 15-parameter creation tool it reads as under-specification rather than genuine conciseness.

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

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

A 15-parameter mutation tool with no annotations, no output schema, and only 47% schema coverage needs a substantive description; a six-word sentence leaves the agent without the information required to call 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 only 47% across 15 parameters, so the description is expected to compensate, and it adds zero parameter information. Roughly half the fields (city, tags, phone, state, address, country, website, annual_revenue) have no documented meaning anywhere.

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

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

States a specific verb and resource ('Create a new account') and the parenthetical '(company)' disambiguates it from the person-oriented create_contact / create_lead siblings. It does not, however, differentiate itself explicitly from update_account or explain its position in the account lifecycle.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. whether the account must be unique, whether an owner is required), and no pointer to alternatives. The agent must infer usage purely from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It does not disclose permission requirements, whether the appointment syncs to a calendar, whether the link is bidirectional, or what happens on failure — only that a record is created.

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

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

A single efficient sentence with no filler, front-loading the core action and following with the linking qualifier. It is appropriately sized, though it is arguably too terse for a 7-parameter mutation tool.

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

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

For a create tool with no annotations, no output schema, and less than half the parameters documented in the schema, the description should cover required inputs and side effects. It leaves the agent without enough to invoke the tool confidently.

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

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

Schema coverage is only 43% across 7 parameters. The description clarifies the linking concept behind targetable_id/targetable_type, but says nothing about the three required fields (title, from_date, end_date), time_zone, or description, leaving most parameters to an under-documented 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 an appointment/meeting') and adds the linking capability, which distinguishes it from siblings like create_task or create_note. It does not explicitly name an alternative tool, but the purpose is unambiguous without opening the schema.

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

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

The 'optionally linked to a contact/account/deal/lead' clause implies when the linking parameters matter, but there is no guidance on when to choose this over create_task, create_note, or other creation siblings, and no prerequisites or exclusions 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?

No annotations are provided, so the description carries the full burden, yet it discloses nothing about behavior: no mention of required fields, authentication need, duplicate-detection/merge semantics, or what the call returns. For a mutation tool with 15 parameters this is a significant gap, though "create" at least conveys that state changes.

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

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

One short, front-loaded sentence with zero waste, but it is under-specified rather than genuinely concise — the brevity comes at the cost of usefulness, especially given the 15-parameter surface.

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 15-parameter mutation tool with a nested custom_field object, no annotations, no output schema, and 40% schema coverage, a single tautological sentence leaves the agent without nearly everything it needs to invoke the tool correctly.

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

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

Schema description coverage is only 40% and the description adds nothing about any parameter. The undocumented majority of fields (city, tags, email, state, country, job_title, numbers, etc.) rely on bare names/types, and even the required first_name is never mentioned in the description.

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

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

"Create a new contact" gives an unambiguous verb (create) and resource (contact), so an agent immediately knows what the tool produces. It does not differentiate this from siblings like create_lead or create_account, or signal how it relates to update_contact, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites (e.g. required first_name), and no mention of alternatives such as update_contact or search_contacts for existing records. The agent must infer all routing decisions from the name alone.

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

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

With no annotations, the description carries the full behavioral burden and does disclose a genuinely non-obvious trait: many Freshsales instances reject creation unless cf_* custom fields are supplied, with a pointer to list_field_choices for verification. It omits permissions/auth requirements, error shapes, and what a successful response contains, so it is strong but not complete.

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, the core action first and the failure-avoidance caveat second, with zero filler. The NOTE earns its length because it prevents a rejected call.

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

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

For a 12-parameter mutation with no annotations and no output schema, the description covers the main hidden pitfall (required custom fields) and names the helper tool for discovery. Return values are not explained, but nothing in the environment provides them either, so the remaining gap is modest.

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 83%, so the baseline is 3, but the description adds real semantic value for the highest-risk parameter: custom_field is where required cf_* values must go, and the instance-dependency of those requirements is stated. It adds nothing for the other dozen parameters, but schema descriptions already cover most of them.

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 is a precise verb+resource statement ('Create a new deal') that is unambiguous against siblings such as update_deal or create_lead, whose names already carry their own scope. It does not explicitly differentiate itself in prose from adjacent creators, but the operation itself is 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?

Usage is only implied: the agent is told to probe list_field_choices before creating and to route required custom fields through custom_field, which is operational prerequisite guidance rather than when/when-not direction. There is no mention of alternatives (e.g. update_deal for existing deals) or conditions under which this call should be preferred.

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 behavioral burden, yet it says nothing. It omits whether fields are optional/required, what defaults apply, whether duplicates are rejected, what happens on missing data, or what the response contains.

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

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

The single short sentence is front-loaded and waste-free, but this is under-specification rather than genuine conciseness. A one-line description for a 15-parameter creation tool earns no credit for brevity.

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 15-property, nested-object creation tool with no annotations and no output schema, the description is completely inadequate. It leaves the agent without the minimum context needed to call 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?

The description mentions no parameters at all while the schema has 15 properties with only 20% description coverage. With 0 required params and undocumented fields like lead_stage_id and lead_source_id, the description fails to compensate for the coverage gap.

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

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

"Create a new lead" states a verb and a resource, so the agent knows it's the lead-creation tool among the siblings. However, it essentially restates the tool name (create_lead) and offers no differentiation from create_contact/create_deal beyond the resource noun, so it sits at the minimum-viable level.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as update_lead or create_contact. The agent is left to infer everything from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about permissions, whether the note is appended to a timeline, editability, idempotency, or what a successful creation returns. For a mutation tool with zero annotation coverage this is a notable gap.

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

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

A single short sentence with the verb and scope front-loaded and no filler. It is efficient, though its brevity contributes to the behavioral gaps noted elsewhere.

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 create tool with full schema coverage and no output schema, the description is minimally sufficient to invoke it correctly. However, the absence of any behavioral context for a write operation leaves it short of 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% and all three parameters are documented in the schema, including the targetable_type enum. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so 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) and resource (note) plus the four record types it targets, which maps cleanly to the enum. It is not confused with any sibling such as create_task or create_appointment, though it does not explicitly differentiate itself from them.

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

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

There is no guidance on when to use this versus other create tools, no prerequisites, and no mention of constraints or alternatives. Usage is only implied by the verb and target list.

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

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

No annotations are provided, so the description carries the full behavioral burden. It notes the link is optional, but says nothing about side effects (notifications, assignment), permission requirements, or whether the task is created for the caller by default.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity comes partly from omitting useful detail rather than from tight editing.

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

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

For a 7-parameter mutation with no annotations and no output schema, the description omits required fields, permission/ownership behavior, and side effects. It covers the linking concept but leaves the agent without enough context to invoke the tool confidently.

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

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

Schema description coverage is 71%, so the schema documents most fields including the targetable_type enum. The description adds that linking is optional and enumerates the four linkable record kinds, but does not clarify owner_id, task_type_id, or the required title/due_date pair.

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 task') and adds the linking scope, which separates it from create_appointment and create_note. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

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

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

There is no when-to-use guidance, no mention of when to prefer create_appointment or create_note, and no prerequisites such as required permissions or the fact that title and due_date are mandatory. Usage is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a safe read and the description discloses a dependency chain (view_id must come from list_views), but it says nothing about pagination defaults, result volume, or ordering behavior despite page/per_page/sort being accepted.

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

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

Two short sentences with zero filler; the purpose comes first and the prerequisite second. Every clause 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 five-parameter list tool with no annotations and no output schema, the description covers the critical prerequisite but leaves pagination and ordering semantics unexplained. Adequate to invoke, incomplete to invoke well.

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 only 40%, so the description must compensate, and it does not: it only restates the view_id provenance that the schema already documents ('View id from list_views'). No meaning is added for page, per_page, sort, or sort_type.

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

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

States a specific verb and resource ('List accounts (companies)') and scopes it with 'from a saved view', which is enough to distinguish it from sibling search_accounts. It stops short of explicitly contrasting the two, so it lands at clear-but-undifferentiated-from-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 a concrete precondition: call list_views(module="sales_accounts") first to obtain the required view_id, which is genuinely actionable guidance. It does not say when to prefer this over search_accounts or when a saved view is the wrong choice, so no exclusions 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?

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing. 'List' weakly implies a read-only operation, but pagination behavior, the default filter (upcoming), result ordering, and return shape are all unstated.

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 single sentence is front-loaded with no filler, but it is under-specified rather than concise: one line cannot carry a three-parameter tool, and the trailing synonym 'meetings' adds no routing 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?

For a simple list tool there is no output schema, no annotations, and no parameter prose, so an agent gets nothing beyond the bare name and a raw schema. The absence of any statement about default filtering leaves a meaningful behavioral gap.

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

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

All three parameters (page, per_page, filter) have 0% schema description coverage, and the description mentions none of them. Critically, the filter enum's default of 'upcoming' is never surfaced in prose, so the description fails to compensate for the schema gap.

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

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

The description states a specific verb and resource ('List appointments/meetings'), so an agent knows exactly what operation it performs. It does not, however, distinguish it from siblings like list_tasks or list_leads beyond the resource noun, so it stops short of a 5.

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

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

There is no when-to-use guidance, no mention of the default 'upcoming' filter scope, and no reference to any alternative tool. The agent must infer everything about applicability from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the view_id dependency but says nothing about pagination behavior, whether the call is read-only, result ordering defaults, or what happens on an invalid view_id.

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

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

Two short sentences with zero filler, and the core action is front-loaded before the prerequisite. 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?

A 5-parameter tool with no annotations, no output schema, and 40% schema coverage needs more than a dependency hint. Pagination, sorting, and return shape are left entirely unexplained.

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 only 40% (page, per_page, and sort_type are undocumented), and the description adds nothing about those. Its mention of view_id essentially repeats the schema's own 'View id from list_views' text, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (list contacts) and scopes it to a saved view, which implicitly separates it from the sibling search_contacts. However, it never names search_contacts as the alternative, so the agent must infer the distinction from the phrase 'from a saved view' alone.

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

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

Provides a concrete prerequisite ordering ('Call list_views(module="contacts") first to get a view_id'), which is genuinely useful setup guidance. It gives no guidance on when to prefer this over search_contacts or view_contact, so usage is only partially implied.

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

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

With no annotations, the description carries the full behavioral burden. It correctly discloses the dependency on list_views to supply view_id, which is genuinely useful, but says nothing about pagination defaults, result caps, or how sorting interacts with the saved view's own filters.

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

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

Two sentences, zero waste, and the core purpose is front-loaded before the prerequisite call. 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 5-parameter tool with no annotations and no output schema, the description covers the critical prerequisite but leaves pagination and sort semantics unexplained, which an agent may need to iterate results 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 coverage is only 40%, and the description compensates for view_id by naming its source tool and giving example values. However, page, per_page, sort, and sort_type remain undocumented in both places, so the compensation is partial.

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

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

The description states a specific verb+resource ("List deals") and adds a scope qualifier ("from a saved view"), so an agent knows exactly what it returns. It does not distinguish itself from the sibling search_deals, which is the main gap keeping it below a 5.

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

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

It gives a concrete prerequisite workflow: call list_views(module="deals") first to obtain the required view_id, even citing example view names. What is missing is guidance on when to prefer this tool over search_deals.

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?

With no annotations, the description carries the full burden and delivers a critical hidden behavior: for cf_* fields a numeric id is silently ignored with a 200 response and no error or change. Disclosing this silent-failure mode is exactly the kind of behavioral context an agent cannot infer from the schema.

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

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

Front-loaded with purpose and usage, then the critical IMPORTANT caveat. The text is dense but every clause earns its place; the parenthetical detail about silent failure is justified by its impact on correctness.

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-param lookup with no output schema, the description covers purpose, when-to-use, the module enum context, field naming, the return shape (id -> label), and the input-type gotcha. 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 coverage is 100% and both params are documented, but the description adds meaning beyond the schema: the rule that built-in fields take the numeric id while cf_* fields take the label STRING. This distinction is not derivable from the schema and directly affects correct invocation.

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 (look up) and resource (a field's definition and valid dropdown choices) with concrete scope including custom fields (cf_*). This is clearly distinguished from the CRUD siblings (create_deal, update_lead, etc.), which mutate records rather than resolve field metadata.

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 it ('before setting a dropdown/custom_field value you don't already know the id for') and provides a worked example (module="deals", field="deal_stage_id"). The condition that selects this tool 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?

No annotations are supplied, so the description carries the full behavioral burden. It discloses the real dependency on list_views, which is useful, and 'List' implies a read-only operation, but it says nothing about pagination behavior despite page/per_page existing, nor about result ordering or limits.

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

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

Two short sentences, zero filler, with the operation stated first and the prerequisite immediately after. Nothing in it is redundant with the name or title.

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 essential prerequisite is covered, which is the most important thing an agent needs. But with no annotations, no output schema, and three undocumented parameters, the description leaves pagination and return-shape behavior entirely unaddressed for a list tool that plainly supports paging.

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 only 40%: sort and view_id are documented in-schema, while page, per_page, and sort_type have no descriptions. The description only alludes to view_id indirectly via the list_views instruction and adds nothing about pagination or sorting semantics, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('List leads') and scopes it ('from a saved view'), which separates it from the sibling search_leads by implying view-driven rather than query-driven retrieval. It stops short of naming search_leads explicitly, so differentiation is inferable rather than stated.

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

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

Gives a concrete prerequisite and call order: 'Call list_views(module="leads") first to get a view_id.' That is actionable guidance an agent can follow without guessing. It does not, however, state when to prefer this over search_leads or what to do if the view returns nothing.

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. 'List all' implies a read-only, unfiltered enumeration, but it does not disclose scope limits (active users only?), ordering, pagination, or permission requirements for a user-listing endpoint.

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

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

One dense sentence with no waste; the resource and the payload ('with their owner_id') are both 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 zero-parameter read tool with no output schema, the description adequately covers what is returned (CRM users plus their owner_id). It falls short only on behavioral details like return ordering or whether the list is scoped to active owners.

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 schema has zero parameters, so there is nothing for the schema to document and the baseline is 4. The description correctly implies the call takes no filters.

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 CRM users who can own leads/contacts/accounts/deals') and even names the returned field (owner_id). It is clearly distinguishable from the CRUD siblings, though it doesn't explicitly contrast itself with any of them.

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

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

Usage is only implied: the mention of 'owner_id' hints this is the reference lookup you call before assigning owners on leads/contacts/etc., but there is no explicit when-to-use statement or pointer to the tools that consume owner_id (create_lead, update_deal, etc.).

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 behavioral burden and discloses almost nothing. It never states that this is a read-only operation, how pagination behaves despite page/per_page parameters, or what the default filter ('open') means for results.

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

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

A single front-loaded sentence with no padding, so it is structurally clean. The problem is under-specification rather than verbosity, but as written every word earns its place.

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

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

With no annotations, no output schema, and 0% parameter description coverage, the description is the only source of behavioral information and it is nearly empty. An agent cannot learn pagination, defaults, or result scope from it.

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

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

Schema description coverage is 0%, so all three parameters are undocumented in the schema, and the description only gestures at filtering without explaining the enum values, the 'open' default, or page/per_page semantics. It does not compensate for the coverage gap.

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

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

The phrase 'List tasks' names a clear verb and resource, but 'optionally filtered' is vague and adds nothing an agent couldn't infer. It makes no attempt to distinguish this from siblings like list_appointments, list_leads, or create_task/update_task.

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?

'Optionally filtered' weakly implies you can narrow results, but there is no when-to-use guidance, no mention of when to reach for this versus search or list_views, and no exclusions. An agent gets no routing help from the description.

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

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

No annotations are provided, so the description carries the disclosure burden. It clearly conveys a read-only lookup and, more valuably, discloses the downstream dependency that makes the output a required input for other tools. It does not mention auth requirements or pagination, which is a minor gap for a simple lookup.

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

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

Two sentences, zero filler, and the dependency instruction is placed immediately after the purpose statement. Every clause earns its place.

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

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

With no output schema, the description still signals what is returned (view ids and named filters) and why it matters. For a single-parameter lookup tool, 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 description coverage is 100% with a fully enumerated module parameter, so the baseline is 3. The description adds only illustrative view names ('All Contacts', 'Open Deals', 'My Leads') rather than clarifying module-to-view mapping or other parameter 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?

States a specific verb and resource ('List the saved views (filters)') scoped to a module, which clearly distinguishes it from the sibling list_leads/list_contacts/list_deals tools. An agent can tell exactly what it returns 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 instructs 'call this first' and names the dependent tools (list_contacts/list_accounts/list_deals/list_leads) that require the returned view id. This is a textbook when-to-use directive with the alternative path made 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?

No annotations are provided, so the description carries the entire behavioral burden. It does not state that the operation is read-only, how results are ordered or capped, whether pagination exists, what permissions are required, or how results from different record types are merged. Only the searchable field set is disclosed.

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

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

A single sentence with no filler, and the scope (across which entities) is front-loaded before the match fields. Nothing is redundant or padded.

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

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

There is no output schema and no annotations, so the description must carry the return-value story — and it doesn't. For a unified multi-entity search, an agent needs to know whether it returns mixed-type records, how they are grouped or ranked, and any result limits. Only the input side is addressed.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, making 3 the baseline. The description does add one piece of value beyond the schema's bare 'Search term' by naming the matchable fields (name/email/keyword), but says nothing further about the 'include' filter or query syntax.

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 (search) and enumerates the resources covered (leads, contacts, accounts, deals) plus the matchable fields (name/email/keyword). The word 'unified' hints at the cross-entity scope, but the description never explicitly contrasts itself with the sibling search_leads/search_contacts/search_accounts/search_deals tools, so the differentiation is only implied.

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

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

No when-to-use guidance at all. With four entity-specific search siblings present, the central decision an agent faces is 'unified search vs. targeted search,' and the description is silent on it. It also omits any prerequisite or exclusion 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?

No annotations are provided, so the description carries the full burden. It doesn't disclose behavioral traits such as pagination, result limits, fuzzy vs exact matching, or whether it searches only account names or also associated fields. For a search tool, this is a significant gap.

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

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

A single, efficient sentence that is front-loaded with the core action. 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 search tool with no annotations and no output schema, the description is incomplete. It doesn't explain return format, result limits, or how to use the results. The sibling list includes list_accounts and view_account, but the description doesn't help an agent choose between them.

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 single parameter 'query' is already documented. The description adds minor value by specifying that the query searches name/domain/keyword, but doesn't elaborate on syntax or matching behavior.

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 (search) and resource (accounts/companies), and clarifies what fields are searchable (name/domain/keyword). It distinguishes from list_accounts and view_account by being a search operation, though it doesn't explicitly differentiate from search_leads/search_contacts.

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

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

No guidance on when to use this tool versus alternatives like list_accounts or view_account. The description implies a search context but doesn't state exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only operation, whether matches are partial or exact, whether there are result limits or pagination, or whether empty results are returned for no match.

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

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

A single front-loaded sentence with no padding, appropriate for the tool's simplicity. It is efficient but extremely sparse, leaving no room for the routing or behavior context an agent might want.

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 search tool with no output schema and no annotations, this is the minimum viable definition. The critical missing piece is the read-only/matching behavior, but the surface area is small enough that little else is required.

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% (only the single 'query' parameter, documented as 'Search term'), so the baseline is 3. The description does add a small amount of meaning by naming the fields the term is matched against (name/email/keyword), which goes slightly 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 (search) and resource (contacts) plus the fields matched (name/email/keyword), so an agent can distinguish it from search_leads, search_deals, and search_accounts by resource. It stops short of explicitly contrasting with the generic sibling 'search', which is the one place ambiguity remains.

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

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

No when-to-use guidance, no mention of alternatives such as list_contacts or view_contact, and no indication of prerequisites. The agent must infer that this is the keyword-lookup path versus enumeration.

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?

With no annotations provided, the description carries the full behavioral burden, yet it discloses nothing about matching semantics (partial vs exact), result caps, pagination, or that this is a read-only operation. A single line is insufficient for an unannotated 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?

A single efficient, front-loaded sentence with zero filler. It is terse to the point of under-specification rather than bloated.

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 search tool with no output schema and no annotations, the description is minimally adequate but omits return shape, result limits, and how the query matches. It leaves real gaps an agent would want filled.

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 query parameter is already documented as 'Search term', so the schema does the heavy lifting. The phrase 'by name/keyword' adds only marginal clarification about which fields are matched.

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 (search) and resource (deals) plus the matching field (name/keyword), so the agent knows what it does. It does not differentiate itself from siblings like list_deals or search, leaving the sibling distinction to inference.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_deals for unfiltered enumeration or search for global queries. The agent gets no routing help.

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 disclose matching semantics (exact vs partial, case sensitivity), result caps, pagination, or ordering — all material for a search 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?

One sentence, front-loaded with verb and resource, no filler. It is arguably terse rather than padded, so it earns its space even if more was needed.

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 search with no annotations and no output schema, the description is minimally viable. Missing search semantics and result-set behavior leave real gaps for an agent calling 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?

Single required parameter with 100% schema coverage, so baseline 3 applies. The description does add value by naming what the query matches against (name/email/company/keyword) beyond the schema's bare 'Search term'.

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 (search) and resource (leads) plus the fields matched against. It does not differentiate from siblings such as list_leads (enumeration) or search_contacts/search_deals, so the agent must infer the boundary from the name alone.

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

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

No guidance on when to use this versus list_leads, view_lead, or the other search_* tools. The description assumes the agent already knows a keyword search is the right choice.

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 of behavioral disclosure and delivers almost none. 'Update' implies mutation, but it never states whether omitted fields are preserved or cleared, whether permissions are required, or how errors are surfaced. The one useful hint, the picklist/label caveat, lives in the schema rather than the description.

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

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

A single front-loaded sentence with zero filler. It is efficiently sized, though the brevity is a symptom of under-specification rather than disciplined editing.

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 16-parameter mutation tool with no annotations, no output schema, and near-zero schema coverage, this description is far too thin. It omits partial-update semantics, required vs optional behavior, and any reference to helper tools like list_field_choices or list_owners for the id-typed fields.

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 16 parameters and only 13% schema description coverage, the description must compensate for the gap and instead adds nothing — it names no updatable fields, no format rules, and no id-vs-label distinctions. The only substantive parameter documentation (custom_field, account_id) comes from the schema itself, not the description.

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 an existing account') and adds the disambiguating gloss '(company)', which separates it from lead/contact/deal updates at a glance. It does not, however, explicitly contrast itself with siblings like create_account or update_contact, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as create_account, view_account, or search_accounts, and no mention of prerequisites like resolving an account_id first. The agent must infer usage entirely from the tool name.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'update an existing contact' and omits whether this is a partial or full update, permission requirements, reversibility, which fields are mutable, and error behavior.

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

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

The single sentence is concise but severely underspecified for a 16-parameter mutation tool. Conciseness is not the issue; lack of appropriate sizing and front-loaded detail is.

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 annotations, no output schema, 16 parameters at 6% coverage, and a nested object, the description is far from complete enough for an agent to invoke the tool correctly. It provides no behavioral, parameter, or usage 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?

The schema has 16 parameters with only 6% description coverage (only contact_id is described), and the description adds no parameter meaning at all. It does not clarify the updatable fields, the nested custom_field object, or any constraints.

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

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

States a clear verb (update) and resource (contact), so the basic purpose is unambiguous. However, it does not differentiate from sibling update tools such as update_lead or update_account, which is necessary given the crowded sibling set.

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

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

No guidance on when to use this tool versus alternatives like update_lead or update_account, and no prerequisites (e.g., that the contact must already exist) are stated. The description merely implies usage from the verb 'update'.

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 behavioral burden. It conveys that this is a mutation but says nothing about whether it is a partial or full update (only deal_id is required, which strongly suggests partial), permission requirements, reversibility, or what happens to unspecified fields. For a 13-parameter write tool with zero annotation coverage, that is a substantial gap.

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

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

A single tight sentence with the core action front-loaded and the examples parenthetically appended, so nothing is wasted. It is arguably too short for a 13-parameter tool, but that is a completeness issue rather than a conciseness flaw.

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 a mutation tool with no annotations, no output schema, a nested custom_field object, and 15% schema coverage across 13 parameters, the description is far too thin. It should at minimum clarify partial-update semantics and the custom_field handling to let an agent invoke it confidently.

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

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

Schema description coverage is only 15% — just deal_id and deal_stage_id are documented, and the latter usefully points at list_field_choices. The description mentions only three fields (stage, amount, owner) out of thirteen, so the remaining ten parameters (tags, custom_field, expected_close, pipeline, sales_account, etc.) are undocumented in both schema and description. The description does not compensate for the coverage gap.

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

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

States a specific verb and resource ("Update an existing deal") and illustrates the operation with concrete examples (stage move, amount/owner change). The update_* naming pattern makes it distinguishable from create_deal, view_deal, list_deals, and search_deals without opening the schema, though the description itself does not name those siblings.

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

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

The word "existing" implies this is for records that already exist, but there is no explicit when-to-use guidance, no mention of when to prefer create_deal or search_deals first, and no stated prerequisites such as needing a valid deal_id. Usage is left entirely to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only implies mutation. It says nothing about partial vs. full updates, required permissions, whether omitted fields are preserved or cleared, or how the custom_field object is merged.

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 single short sentence is front-loaded and contains no filler, but it is concise to the point of under-specification given the tool's complexity. Brevity here reflects a missing payload rather than disciplined editing.

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

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

A 16-parameter mutation tool with no annotations, no output schema, a nested custom_field object, and near-zero schema coverage is left almost entirely unexplained. An agent cannot call this correctly without guessing at field semantics and update 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 6% — only lead_id is documented — and the description adds no parameter meaning whatsoever for the remaining 15 fields (email, tags, owner_id, custom_field, etc.). With such low coverage, the description must compensate, and it does not.

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

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

The description states a specific verb and resource ('Update an existing lead'), which is enough for an agent to distinguish it from create_lead, view_lead, and list_leads. It does not, however, indicate what aspects of the lead can be modified or how it differs from update_contact/update_deal beyond the resource noun.

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

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

There is no guidance on when to use this tool versus alternatives such as update_contact, create_lead, or the custom_field pathway. No prerequisites, no conditions, and no exclusions 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?

With no annotations, the description carries the full burden, and it does add one genuinely valuable disclosure: the accepted "status" value is unverified and rejection should be handled by retrying. Beyond that it says nothing about permissions, whether omitted fields are left untouched, or partial-update semantics for a mutation 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?

Two tight sentences, with the primary purpose front-loaded before the caveat. The second sentence is hedged but earns its place by flagging a real failure mode.

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

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

For a 6-parameter mutation tool with no annotations, no output schema, and 33% schema coverage, the description covers the highest-risk item (unverified status enum) but omits permissions, required-vs-optional behavior, and how unspecified fields are treated. Adequate, 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 only 33%, so the description must compensate; it partially does by mapping use cases onto parameters (reschedule→due_date, reassign→owner_id, mark done→status) and warning that the status value is unverified. However, title and description params remain undocumented anywhere, and no format hints are given for due_date.

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

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

States a specific verb and resource ("Update a task") and enumerates the three common mutations (reschedule, reassign, mark done), so the agent knows exactly what it does. It does not distinguish itself from siblings such as update_lead or update_contact, but the resource 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 examples (reschedule, reassign, mark done) imply when to reach for this tool, but there is no explicit when-not guidance and no alternative tool is named. The only operative instruction is reactive — "check the result and adjust if rejected" — which is not a routing rule.

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?

With no annotations, the description carries the full behavioral burden, and it delivers very little: no statement about permissions/authentication, behavior on an invalid or missing ID, or what 'detailed' actually encompasses. It does not contradict anything, but it discloses almost nothing beyond the verb.

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

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

A single short, front-loaded sentence with no filler or repetition. It is efficient, though it is efficient at saying very little.

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

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

For a one-parameter read tool with no output schema, the description is minimally adequate but leaves the agent guessing about the shape of 'detailed information' and the error behavior. Adding one clause about what is returned would close the gap.

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

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

Schema coverage is 100% for the single parameter, so the schema already documents account_id fully; baseline 3 applies. The description adds no format or sourcing detail (e.g., where to obtain the ID) 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 ('View') and resource ('account'), with the parenthetical '(company)' disambiguating the domain term. However, it does not differentiate itself from siblings like search_accounts or list_accounts, which an agent must infer from the required account_id.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as search_accounts or list_accounts. The presence of a required account_id only implicitly signals 'fetch one record by ID'.

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 behavioral burden. 'View' implies a safe read operation, which is useful, but it says nothing about permissions, behavior when the contact_id doesn't exist, or what 'detailed information' comprises.

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

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

A single front-loaded sentence with zero filler. Every word earns its place and the core action is stated immediately.

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 one-parameter read tool with no output schema, the definition is adequate but thin. It doesn't describe the returned fields or error behavior, leaving the agent to infer what 'detailed information' means.

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 required param (contact_id) is documented in the schema. The description adds no syntax, format, or ID-source guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('View') and resource ('contact') with a scope qualifier ('detailed information'). This differentiates it from list_contacts and search_contacts by implying single-record retrieval, though it doesn't name those siblings explicitly.

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

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

Usage is only implied: retrieving one contact is clearly distinct from listing or searching, but the description never states when to prefer this over search_contacts or list_contacts, nor any prerequisite such as needing a known contact_id.

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 disclosure burden. 'View' implies a read-only lookup, but the description says nothing about failure behavior for an unknown/missing deal_id, permission requirements, or what 'detailed information' actually encompasses.

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

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

One short, front-loaded sentence with zero padding or redundancy. It is efficiently sized for a simple lookup tool, though the terseness contributes to the gaps noted elsewhere.

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 read tool with full schema coverage this is minimally adequate, but with no output schema the agent has no idea what fields 'detailed information' returns, and the description does nothing to compensate for that missing return-shape 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% for the single deal_id parameter, so the schema already documents it. The description adds no syntax, format, or sourcing guidance (e.g., where to obtain the ID), 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?

The description names a specific verb ('View') and resource ('deal'), so an agent immediately knows this retrieves one deal. However, it offers no differentiation from the closely related siblings search_deals and list_deals, leaving the boundary between them to inference.

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

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

There is no when-to-use or when-not-to-use guidance. The description never explains that this is the single-record counterpart to search_deals/list_deals, nor does it state any prerequisite such as having obtained a deal_id first.

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 behavioral burden and contributes almost nothing: 'view' weakly implies a read-only operation, but there is no statement about permissions needed, whether the lead must be owned by the caller, or what happens with an invalid ID. For a tool with zero annotation coverage this is a notable gap, though low risk since it is a retrieval.

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

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

A single short sentence, front-loaded with the verb and resource, with no filler or redundancy. Its brevity borders on under-specification, but nothing in it is wasted.

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

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

For a simple one-parameter lookup this is roughly adequate, and with no output schema it need not enumerate return values. Still, it never characterizes the response ('detailed information' is vague) or clarifies its relationship to search_leads/list_leads, leaving room for the agent to pick the wrong retrieval tool.

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

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

Schema description coverage is 100%, so lead_id ('Lead ID') is already documented, and the description adds no format, range, or sourcing detail beyond it. With the schema doing all the work, the baseline 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 gives a specific verb ('View') and resource ('a lead') with a scope qualifier ('detailed information'), so the agent knows it is a single-record fetch rather than a list. It does not, however, distinguish itself from the nearby siblings list_leads, search_leads, or update_lead, which share the same resource.

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

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

There is no guidance on when to choose this over search_leads or list_leads, nor any stated prerequisite such as already holding a lead_id. The single required parameter implies a lookup-by-ID use case, but that inference is left entirely to the agent.

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