Groundbase

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

Without annotations, the description carries the burden of behavioral disclosure. It reveals that results are ordered most recent first and enumerates the activity types covered, which goes beyond the schema. However, it doesn't state whether this is a read-only operation, how results are paginated, or what the return shape looks like.

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 three sentences, with the resource and content front-loaded, followed by ordering and use cases. No filler or repetition of schema details. It 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?

For a read-oriented list tool with four optional, well-described parameters, the description conveys what the feed contains, its ordering, and when to use it. The lack of an output schema is partially mitigated by the listing of activity types, though pagination and limits are only detailed in the schema.

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

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

The schema covers all four parameters with descriptions, so the baseline is 3. The description doesn't add parameter-level meaning beyond the schema's own descriptions and the 'with X' use-case phrasing. Since schema coverage is 100%, no deduction is warranted.

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

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

The description clearly identifies the tool as an aggregated activity feed covering SMS, calls, emails, notes, deal stage changes, and task completions, with a reverse-chronological order. It is distinct from sibling tools like calls_list or notes_list because it combines multiple activity types, even though it doesn't name them as alternatives. This is a clear statement of purpose, but explicit sibling differentiation is not provided.

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 concrete use cases: summarizing 'what happened with X' and building a weekly CRM activity digest. This tells an agent when the tool is appropriate. It doesn't name exclusions or alternatives, but the provided scenarios are sufficient context for typical 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 are provided, so the description carries the full burden. It discloses that all fields are optional and that a city alone is a valid record, which adds behavioral context. It also clarifies the one-of relationship between contactId and companyId. It doesn't mention response format or error handling, but for a create operation this is acceptable.

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 three short sentences with zero fluff. The action is front-loaded, and the two key constraints (one-of, optionality) follow directly. Every sentence earns its place; there is no redundant information.

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

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

For a create tool with 0 required parameters and no output schema, the description covers the essential behaviors: the action, the one-of constraint, and optionality. It doesn't discuss validation errors or return values, but these are less critical given the tool's simplicity. The schema already describes is_primary's demotion behavior, so the description doesn't need to repeat 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 60%, leaving city, country, companyId, and contactId undocumented. The description compensates by clarifying the exact-one-of rule for contactId/companyId and stating all fields are optional. This adds meaning beyond the schema for the critical parameters. The remaining fields are self-explanatory.

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: 'Add an address to a contact or company.' It uses a specific verb and resource, and distinguishes itself from sibling tools like addresses_update and addresses_delete by the action. The one-of constraint (contactId/companyId) is front-loaded, leaving no ambiguity.

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

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

The description provides clear usage context: to create an address for a contact or company. It explicitly states the rule to pass exactly one of contactId or companyId, which is a direct usage guideline. It doesn't compare to alternatives like addresses_update, but the purpose is self-evident from the name and 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?

With no annotations, the description carries the burden of behavioral disclosure. It states the side-effect scope ('does not touch the contact or company itself'), which is valuable, but it does not mention whether deletion is permanent, what happens if the addressId is invalid, or any permission requirements.

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

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

Two short sentences with no filler. The core action is front-loaded and the important scoping caveat follows immediately, making the description easy to parse.

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

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

The description is sufficient for a simple delete operation using the required addressId, but it lacks guidance on the optional parent IDs and gives no indication of response or error behavior. Given the absence of annotations and output schema, this leaves notable gaps for an agent deciding how to invoke the 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 only 33%, and the description does not explain the roles of companyId or contactId or when to use them. The addressId parameter is documented only as 'From addresses_list', leaving the polymorphic address-to-parent relationship under-specified.

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 ('Remove'), a precise resource ('one address'), and the applicable parent types ('contact or company'). It also distinguishes itself from parent-entity deletion tools by clarifying that the contact or company itself is untouched.

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 clearly targets deletion of an address and explicitly rules out deleting or altering the parent entity, which helps distinguish it from addresses_update, contacts_delete, and companies_delete. It does not name alternative siblings like addresses_update, but the intended use case is reasonably clear.

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

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

With no annotations provided, the description carries the full burden. It clearly implies a read-only operation ('List') and explains that addresses are separate records, which is important behavior not evident from the name alone. However, it does not mention potential errors when both or neither ID is passed, or whether empty results are possible, but for a simple list tool this is adequate.

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 only two sentences, with the core purpose and usage rule front-loaded. The second sentence adds a valuable clarification without redundancy. Every sentence serves a purpose, and there is no fluff.

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

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

Given the tool's simplicity (no output schema, only two optional parameters), the description is essentially complete. The main information an agent needs—what it does, when to use it, and parameter constraint—is covered. A minor omission is not specifying what happens if both or neither IDs are passed, but this could be inferred from the instruction 'exactly one' and may not be necessary.

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 provides descriptions for both parameters (companyId and contactId) with 100% coverage, so the schema already explains them. The description adds the crucial semantic that exactly one must be provided, which is not in the schema. This goes beyond the schema and clarifies the mutual exclusivity, providing added value.

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 'List the addresses on a contact or company' with a specific verb and resource. It also distinguishes itself from related tools like contacts_get and companies_get by noting that addresses are separate records, which differentiates it from siblings that might also fetch contact or company data.

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 'Pass exactly one of contactId / companyId', providing a clear usage rule. It also guides when to use this tool ('when asked where somebody is') and when not to (addresses do not appear in contacts_get or companies_get), effectively distinguishing it from those 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?

With no annotations, the description carries the full burden. It discloses the partial-update behavior ('Only the fields you pass are altered') and warns about the id distinction. However, it omits details on errors, idempotency, or return values. For a simple update tool, this is adequate but not rich.

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 three concise sentences, front-loaded with the main purpose, followed by a usage prerequisite and a caution. No waste; 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 partial-update tool with one required parameter, the description covers the essential: what it does, how to obtain the ID, and the partial-update behavior. It lacks return-value or error details, but those are not critical for an update operation. The absence of an output schema and annotations is partially mitigated by the clear usage guidance.

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 64%, so the schema documents many parameters. The description adds the key semantic that only passed fields are altered, and clarifies the addressId vs contactId confusion. It does not describe the parameters missing from the schema, but it compensates somewhat for the update 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?

The description states a clear verb and resource ('Change one address') and distinguishes it from sibling tools like addresses_create and addresses_delete. It also clarifies the partial-update semantics, making the tool's purpose unambiguous.

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

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

The description explicitly instructs to use addresses_list first to obtain the addressId and warns that address id is not contact id. This provides a clear prerequisite and a common pitfall, though it doesn't explicitly state when not to use the tool (e.g., for creation). The sibling list makes alternatives 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?

With no annotations, the description must fully disclose behavior. It does explain that currency/terms set here become invoice defaults, but it does not clarify create-vs-upsert behavior, error handling for both/none of contactId/companyId, permissions, or side effects on existing profiles. This is a significant gap 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?

The description is two sentences with no filler; the core purpose and key constraint are front-loaded. It could be better structured with a bullet list for the constraint, but it is efficient and readable.

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

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

For an 8-parameter create tool with no annotations and no output schema, this description is incomplete. It does not state the return value, conflict behavior, or how it differs from the similarly named billing_profiles_create. The mutual-exclusivity hint is valuable but not enough.

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

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

Schema coverage is only 38%, so the description must compensate. It adds the essential constraint that exactly one of contactId/companyId is required and clarifies the downstream effect of currency and paymentTermsDays. However, it leaves notes, taxId, billingEmail, and billingAddress unexplained.

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 action ('Attach billing details') and a resource ('contact or company'), and adds the key mutual-exclusivity constraint. However, it does not differentiate from the nearly identically named sibling tool billing_profiles_create.

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?

Offers useful context about currency/terms defaulting to invoices, which implies a scenario for use, but does not explicitly state when to use this tool over billing_profiles_create, billing_profiles_update, or other alternatives. No when-not guidance is provided.

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. It usefully discloses that null is a normal return value and clarifies the data model. However, it does not explain what happens if neither companyId nor contactId is provided, or whether supplying both is allowed or which takes precedence.

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

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

Three concise sentences, all adding value. The core purpose is front-loaded, and the clarifications about null returns and data location are relevant and efficiently worded.

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

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

The description explains what is returned and the normal null case, which is helpful given there is no output schema. However, it omits parameter decision rules and does not address the plural sibling, which an agent would need to select this 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 0%, so the description must compensate. It does map the parameters to entities: companyId for company and contactId for contact, but it does not clarify whether one is required, whether they are mutually exclusive, or any format expectations. Some meaning is added, but key semantics remain unclear.

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 identifies the action (get), the resource (billing profile), and the target entities (contact or company), listing the fields returned. It also distinguishes billing details from a separate customers list. However, it does not explicitly differentiate itself from the similarly named sibling billing_profiles_get, which is a notable ambiguity.

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

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

The description implies when to use this tool: when you need a single billing profile for a contact or company, especially since billing details hang off the contact record. But it never explicitly states when not to use it or what alternatives like billing_profiles_get are for.

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 behavioral burden. It discloses the mutual exclusivity of contactId/companyId and the persistent side effect that future invoices automatically adopt currency and terms. This goes beyond what the schema alone reveals, though it does not cover error behavior, idempotency, or return values.

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

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

The description is two sentences with no filler. The most critical constraint is front-loaded, and the behavioral consequence is stated efficiently in the second sentence.

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

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

The description captures the core intent, the cardinality constraint, and the automatic effect on invoices, which is enough for basic use. But with eight parameters, no annotations, no output schema, and no guidance on defaults or lookup requirements, the context is 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 only 38%, and the description compensates partially by clarifying that contactId and companyId are mutually exclusive and that currency/payment terms have ongoing effects. However, it does not add meaningful semantics for several parameters like notes, taxId, or billingAddress.

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

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

The description clearly states the action ('attach invoicing details'), the resource affected ('contact or company'), and a key constraint ('exactly one of contactId or companyId'). However, it does not differentiate itself from the near-identically named sibling 'billing_profile_create', so it falls short of full clarity.

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

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

The description provides no explicit guidance on when to choose this tool over alternatives. There is a confusing sibling named 'billing_profile_create' that is never mentioned or contrasted, and no exclusions or preferred contexts 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 burden of behavioral disclosure. It usefully discloses that a missing profile returns 'nothing' and that this is not a billing problem, but it does not explain behavior when both or neither identifiers are supplied, or describe the return format.

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 focused sentences, no filler. The primary lookup behavior is front-loaded, and the second sentence adds meaningful context about the no-profile case 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?

For a simple getter, the description covers the main purpose and an important edge case. It is incomplete regarding identifier selection rules and does not clarify what 'nothing' means in practice, especially since both parameters are optional and there is no output schema.

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

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

The schema has 0% description coverage, so the description must compensate. It conveys that the profile belongs to one contact or company, which hints at companyId/contactId usage, but it does not explicitly map these to parameters or clarify whether one identifier is required given that both are optional in the schema.

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

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

The description clearly states the tool retrieves the billing profile for one contact or company and returns nothing when none exists. The verb and resource are specific, though it does not distinguish itself from the similarly named sibling billing_profile_get.

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

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

The description implies this is a single-profile lookup by contact or company, and explains the no-profile case. However, it gives no explicit guidance about when to prefer this over billing_profiles_list or billing_profile_get, nor does it state exclusions.

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 makes the read-only list behavior clear and adds the precondition that a billing profile attaches to an already-existing contact or company. Still, it does not mention pagination, limits, authentication, or response shape, which an agent may need when invoking a list operation.

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

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

The description is two sentences with the core action front-loaded in the first sentence. The second sentence explains the resource and adds one clarifying exclusion. There is no redundancy or filler; 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 zero-argument list tool with no annotations and no output schema, the description covers the key essentials: what it lists, its scope, the resource definition, and the contained fields. It falls slightly short on operational details like pagination or response envelope, but for this simple tool the coverage is largely 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?

The input schema has zero parameters, so the baseline for this dimension is 4 and the description is not required to explain parameter behavior. It still adds helpful domain meaning by enumerating the invoicing details each profile contains (currency, payment terms, billing address, tax id), which helps an agent interpret results.

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

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

The description opens with 'List every billing profile,' which names a specific verb and resource and clearly marks this as the list-all operation. It distinguishes the tool from billing_profiles_get, billing_profiles_create, and billing_profiles_update by scope and action, and it further clarifies the domain by explaining what a billing profile is and noting there is no separate customers list.

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 useful domain context and preemptively tells the agent that no separate customers list exists, which helps prevent a wrong search. However, it never explicitly contrasts this tool with sibling tools like billing_profiles_get or says when to prefer listing all profiles over fetching one. Usage guidance is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal a key trait: partial updates ('Only the fields you pass are touched'), which is valuable. However, it omits other behaviors like validation rules, error handling, or permission requirements, leaving gaps.

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 at two sentences, front-loading the core action and then the partial-update behavior. It has no filler and is easy to parse, though it could be slightly more structured by enumerating example parameters.

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 annotations, no output schema, and 0% parameter coverage, the description is incomplete. It only covers the update semantics but lacks information about required fields, input formats, return values, or error conditions, which an agent would need 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 0%, and the description adds no parameter-specific information. It does not explain what 'id', 'notes', 'taxId', 'currency', etc. represent or how they should be formatted. This is a significant deficiency for a 7-parameter tool.

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

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

The description clearly states the verb 'Change' and the resource 'billing profile', and it implicitly differentiates from sibling tools like billing_profile_create and billing_profiles_get. It does not list specific fields, but the schema provides them, so the purpose 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?

There is no explicit guidance on when to use this tool versus alternatives, such as when to create a new profile or list existing ones. The description implies it is for modifying an existing profile but does not state prerequisites (e.g., that an ID is required) or conditions for choosing it over other billing-related tools.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does a good job by describing what the return includes — full call record, voicemail transcript, recording details when present — and 'Get' signals a read-only operation. It omits error behavior, but that is not essential for a simple retrieval 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 short sentences with no filler. The main purpose and return contents come first, and the required id provenance is stated 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 single-parameter get tool with no output schema, the description is complete: it identifies what is returned, notes optional components, and tells the agent where to obtain the id. No critical information is missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already explains that id is a 'Call id from calls_list'. The description repeats this rather than adding new semantic detail, 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 and resource: 'Get one call record in full', and sharpens the scope by naming the distinguishing contents — voicemail transcript and recording details when present. It also positions itself against calls_list by saying it 'Takes an id from calls_list', so an agent can tell the two apart.

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 clear context: this tool is for retrieving a single full call record after obtaining an id from calls_list. It does not explicitly list exclusions or alternative tools, but the workflow implication is unambiguous for the relevant sibling.

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 transparency burden. It discloses output content (inbound/outbound, duration, direction, voicemail transcripts) and honestly notes transcripts are only included 'where available'. It does not explicitly state read-only behavior, but 'List' strongly implies a non-mutating query.

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

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

Three sentences with no filler: purpose and output fields first, then parameter guidance, then concrete example queries. Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

For a simple filtered-list tool with three fully documented parameters and no output schema, the description covers what the tool returns, how to filter, and real user questions it answers. An agent has enough context to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to contactId and voicemailOnly by tying them to user intents ('see calls with one person', 'see just calls that left a voicemail'). The limit parameter is not re-explained, but the schema already fully documents it.

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 uses a specific verb ('List') and resource ('the user's call history'), then names key result fields and filter options. It is clearly distinguishable from the sibling calls_get, which implies single-record retrieval, without needing to open the schema.

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

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

The description gives concrete use cases ('who did I speak to this week?', 'did anyone leave a message?') and explains when to use contactId and voicemailOnly. It does not explicitly mention alternatives or when not to use this tool, so it stops short of a full 5.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It divulges that results are aggregated (including unique vs. total counts), which is helpful, but it does not explicitly state read-only behavior, error cases, or aggregation scope. This is adequate but incomplete.

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 tightly packed sentences: the first enumerates the entire result set, and the second gives concrete use cases. No wasted words, and the core purpose is front-loaded.

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

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

Despite lacking an output schema, the description lists every metric returned scaffolding completeness. The single parameter is fully documented in the schema dropped. Minor gaps like aggregation timeframe or prerequisites do not undermine usability for a low-complexity analytics read.

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 already describes the only parameter as 'Campaign UUID' with 100% coverage. The description adds no additional parameter semantics, 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?

The description clearly identifies the resource as aggregated stats for one campaign and enumerates the specific metrics returned. It does not explicitly contrast with sibling tools, but the 'one campaign' scope and metric list make its purpose distinct from broader tools like dashboard_summary.

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

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

It provides explicit usage scenarios: answering how a newsletter performed or picking the best-performing campaign. It does not mention exclusions or alternatives, but the stated use cases give clear context for when to invoke it.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does describe the output shape, status filtering, and per-event timestamps. However, it does not mention pagination behavior beyond the schema's limit parameter, ordering, rate limits, or potential failure modes.

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

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

The description is front-loaded with the core operation and return shape, and the usage examples earn their place by clarifying when to call the tool. It is slightly longer than strictly necessary, but every sentence adds useful context.

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

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

For a fairly simple list tool with three parameters and no output schema, the description covers the purpose, output fields, optional filtering, and practical use cases. Minor gaps remain around pagination and ordering, but an agent has enough 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 100%, so the schema already documents all three parameters. The description adds meaning by giving concrete filter examples ('status='opened'' for everyone who opened), but it mostly restates what the schema already communicates.

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 per-recipient status for one campaign, enumerates the exact fields returned, and covers the event types. It distinguishes itself from sibling tools like campaigns_analytics by focusing on per-recipient rows rather than aggregate analytics.

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

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

The description provides clear use cases ('who didn't open my newsletter', 'who clicked the call-to-action') and shows how the status filter supports them. It does not explicitly name sibling alternatives or explain when not to use the tool, but the practical examples give strong contextual 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?

With no annotations, the description carries the full behavioral burden and delivers: soft-delete semantics, update-only-when-draft/scheduled/paused, sending_window waits instead of failing, reply-exit blindness with unconnected reply_to addresses, the content_json/content alias bug, unverified-domain failure at send time, and ongoing-vs-once enrollment behavior. These are material operational traits that no schema or annotation would convey.

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

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

The description is long, but it is deliberately organized into action routing, content format, steps, sending window, and audience filter. Front-loading the action verbs helps orientation. The historical note about the content/content_json bug and some duplicated schema prose could be trimmed, but the complexity of the tool justifies most of the 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?

For a 16-parameter tool with nested objects, no annotations, and no output schema, the description is unusually complete. It explains not just what parameters mean but how behaviors play out — what waits, what skips, what fails, and what returns enough fields to audit a campaign. The only notable omission is a full output/return contract for create/send actions, but the described behaviors cover practical calling needs.

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 75%, yet the description still adds substantial meaning beyond the schema: block formats for email/SMS, merge-tag behavior, step delay semantics, exit_on conditions, audience_filter rule shapes, sending_window timezone behavior, and add_recipients behavior. It effectively documents the nested object structures that the schema only names.

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?

Opens with 'CRUD + send-control verbs for marketing campaigns (email or SMS, single send for v1)' — a specific verb category and resource. The explicit action list (list, create, update, send_now, test_send) makes the tool's job unambiguous and separates it from analytics/recipient-list 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 description explicitly routes each action ('Use action='list' to see what's there; action='create' to author...') and gives cross-tool prerequisites like 'call resend_manage(action='domains') first'. It also states status restrictions and drip-mode requirements. It does not explicitly compare against campaigns_preview_audience or campaigns_list_recipients, so it stops short of complete alternative routing.

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

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

No annotations are present, so the description carries full responsibility. It transparently discloses the key side-effect: it does NOT create a campaign, implying read-only behavior. It also specifies the output (count + 5 sample contacts). It could mention error handling or auth requirements, but the main behavioral trait is clearly stated.

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

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

The description is two crisp sentences plus a practical example. It front-loads the core action and side-effect, then gives a use case. No filler words or redundant details.

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 nested filter object and no output schema, the description sufficiently explains what is returned (count + 5 samples) and the validation purpose. It does not detail the sample contact structure or error cases, but for a preview tool this is adequate. The channel default is covered in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the filter's purpose in validation and providing a concrete example (tag=lead). It also clarifies that channel defaults to email, reinforcing the schema. This extra context improves parameter understanding beyond raw 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 resolves an audience filter, returns a count plus 5 samples, and explicitly does not create a campaign. It differentiates itself from campaign creation tools (campaigns_manage) and recipient listing (campaigns_list_recipients) by its non-mutating preview nature.

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 an explicit usage directive: 'Use to validate an audience before action="create".' This is clear context for when to invoke it. It does not enumerate alternative tools or exclusions, but the primary use case is well defined.

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 behavioral disclosure burden. It does add useful behavioral details: name is required, website must include the protocol, and tags are created on the fly if missing. However, it does not mention return values, duplicate handling, or required permissions, so coverage is adequate but not rich.

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

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

Three short sentences with no filler. The primary action is front-loaded, and the additional constraints are concise and relevant.

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

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

For a simple create operation with no output schema location, the description plus schema covers the required name, the website format, and tag behavior. Notes and industry are self-explanatory enough, but a note about the response payload or duplicate-name behavior would improve completeness.

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 50%, so the description needs to compensate for undocumented parameters. It adds meaningful context for tags' auto-creation behavior and reiterates name/website semantics, but it does not clarify notes or industry beyond their property names. This is a minimum-viable pass.

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

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

The description opens with 'Create a new company,' clearly specifying the action and resource. This straightforwardly distinguishes companies_create from sibling tools like companies_update, companies_get, companies_list, and companies_delete.

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 makes it obvious that this tool is for creating a new company, which is the primary usage context. It does not explicitly name alternatives such as companies_update for modifying existing companies, but the 'create' framing provides clear enough context for tool selection.

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 present, the description fully carries the behavioral disclosure burden. It clearly reveals the soft-delete behavior, states that linked contacts and deals are only unlinked and not deleted, and flags the operation as destructive requiring confirmation. This is unusually transparent for a delete tool.

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

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

Three concise sentences with the core action front-loaded and behavioral/safety details placed directly after it. Every sentence adds meaningful information: what the operation does, what happens to related records, and how to handle it safely.

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

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

For a single-parameter destructive delete, the description covers the action, side effects, and confirmation requirement well. It does not describe the return value or how to verify successful deletion, and there is no output schema, but those are minor relative to the safe invocation guidance provided.

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, id, has no description in the schema (0% coverage), and the tool description does not explicitly document it. Context clues such as 'a company' imply id is the company identifier, but the description should have explicitly clarified what id refers to, especially given the lack of schema-level parameter documentation.

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?

Opens with the specific verb-resource pair 'Soft-delete a company,' making the core operation immediately clear. It then disambiguates the side effects by stating contacts and deals are unlinked but not deleted, which distinguishes it from contacts_delete, deals_delete, or a hard-delete operation.

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 capitalized 'DESTRUCTIVE — confirm with the user first' explicitly provides an important usage condition: user confirmation is required before invoking. It does not enumerate alternatives or exclusions such as when companies_update should be preferred, so it stops short of a perfect usage guide.

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 some burden. It discloses that the response includes related data (employees, deals, addresses, custom fields), which is useful. However, it does not mention performance implications, rate limits, or authorization requirements. Given it's a read operation, the lack of destructive hints is not alarming, but more behavioral context (like pagination or data volume) would be helpful.

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 a single, compact sentence that front-loads the primary action and resource, then adds the key detail about included related data. There is no fluff or repetition, and it is immediately scannable.

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 is a simple single-entity fetch with one parameter, the description is largely sufficient. It conveys the core purpose and the scope of the response. It could be slightly more complete by noting any side effects (e.g., read-only nature) or edge cases (e.g., error handling for non-existent ids), but these are minor given the simplicity and no output schema 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 schema has 100% description coverage for the only parameter (id: Company UUID), so the description adds minimal extra meaning for parameters. However, the description does add context by explaining what data will be returned for that id, which is beyond the schema's simple type definition. Baseline is 3, and the added context on return scope justifies a 4.

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

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

Clearly states the action (fetch), the resource (a single company by id), and explicitly lists the included related data (employees, deals, addresses, custom fields). This differentiates it from companies_list (which presumably fetches multiple companies) and other single-entity getters like contacts_get or deals_get.

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

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

The description implies when to use it (when you need a company and its related data), but it does not explicitly state when not to use it or mention alternatives. For example, it doesn't say 'use companies_list to fetch multiple companies' or 'use addresses_list for only addresses'. The inclusion of related resources hints at its richer scope, but lacks explicit 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It goes beyond the obvious 'list' operation by revealing that the API caps the response server-side and that pagination params are advisory until the cap is lifted — a non-obvious behavior that affects invocation. It doesn't cover every behavioral aspect, but the most important caveat 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?

Three sentences with no filler; the core action is front-loaded, use cases follow, and the important caveat is placed at the end. Every sentence earns its place and the structure is easy to scan.

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 with fully documented parameters and no output schema, the description covers the essential call context: what it lists, why to use it, and the pagination caveat. It is slightly less complete than a definition with annotations that explicitly signal safety and read-only behavior, but no critical information for invoking 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?

The schema already covers 100% of the parameters, so the baseline is 3. The description adds value by explaining that limit and offset are advisory because of the server-side cap, which meaningfully changes how an agent should interpret pagination parameters.

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

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

The description opens with a specific verb+resource statement, "List the user's companies," which clearly identifies the operation and scope. It further contextualizes the purpose with concrete use cases (linking a contact, summarizing CRM accounts), which distinguishes it from siblings like companies_get or companies_create.

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 use cases: find a company before linking a contact, or summarize accounts. It does not, however, state when not to use this tool or mention alternative tools like companies_get for retrieving a single company's detailed record, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. The phrase 'Only include fields you want to change' is a useful disclosure that unspecified fields are not overwritten, which adds value beyond the schema. However, it lacks information about permissions, side effects, error behavior, and what happens when the id does not exist.

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 no filler. The operation is front-loaded, and the second sentence provides a distinct, useful constraint about partial updates. 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?

For a mutation tool with no annotations and no output schema, this definition is thin. It does not state what a successful patch returns, how invalid or missing ids are handled, or what values are accepted for fields like size and industry. The simple schema reduces risk, but the agent still lacks operational expectations.

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

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

Schema description coverage is 0%, and the description does not explain individual parameters. The only parameter-level insight is that only changed fields should be included, which lightly complements the schema's optional fields. The property names are self-explanatory, but the description does not compensate for the complete absence of parameter 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 first sentence names the resource ('a company') and a specific verb ('Patch'), which clearly distinguishes it from sibling tools like companies_create, companies_get, and companies_delete. The second sentence reinforces the partial-update nature. It does not explicitly name a sibling, but the create/update/delete/list grouping makes the purpose clear.

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

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

There is no explicit guidance on when to use this tool versus companies_create, companies_delete, or other update tools. The instruction to 'only include fields you want to change' explains how to form the request, not when this tool is the right choice. Usage must be inferred from the tool name and sibling set.

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 full behavioral disclosure. It discloses that phone numbers are normalized to E.164, which is a behavioral trait not inferable from the schema alone (though the schema does mention it). It does not contradict any annotations since none exist.

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 with no wasted words. The purpose is stated first, followed by the key constraint and a normalization note. 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?

The description is adequate for a simple create operation but lacks information about the return value or any side effects beyond what the schema mentions. With no output schema, the agent does not know what the response contains (e.g., contact ID). For a create tool, this is a notable gap.

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

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

The description adds a critical piece of semantics beyond the schema: the requirement that at least one of first_name, last_name, or email must be provided. This is not present in the schema (required: 0). It also reiterates phone normalization, though the schema already covers that. For other parameters, the schema already provides descriptions, so the description doesn't add much there.

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

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

The description states a specific verb and resource ('Create a new contact') and immediately clarifies a key constraint (at least one of first_name/last_name/email). This distinguishes it clearly from contacts_update, contacts_delete, and other contact tools, which are not ambiguous.

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 usage guidance by specifying the minimum required fields, which tells the agent when this tool is appropriate (when at least one of those fields is available). It does not explicitly name alternatives or exclusions, but the context is clear enough for a create tool.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses the soft-delete nature (row hidden but retained), the audit/restore implication, and the need for user confirmation. This goes well beyond the raw schema and gives an agent a reliable picture of side effects and safety expectations.

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

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

The description is a single sentence that leads with the core action, then packs the soft-delete nuance and the mandatory confirmation warning into a compact parenthetical and imperative. No wasted words; every clause adds necessary operational detail.

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

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

For a simple single-parameter delete operation, the description covers the essential aspects: what the tool does, the safety requirement, and the post-delete state. It omits explicit id guidance and any mention of response contents, but those are minor given the tool's simplicity and the clarity of the name and noun.

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 for the lone 'id' parameter. It indirectly identifies the parameter as a contact id via 'a contact,' but it doesn't explicitly state the format or source of the id. The meaning is strongly implied by the tool name and noun, so this is adequate but not exemplary.

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 uses a specific verb and resource: 'Soft-delete a contact,' and immediately clarifies the behavior (hidden from lists but kept for audit/restore). This distinguishes it from cruder interpretations and from sibling tools like contacts_update or addresses_delete, making the tool's purpose unmistakable.

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

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

The description gives clear context: this is the tool for deleting a contact, and it adds an explicit safety condition—confirm with the user unless they explicitly asked to delete. It doesn't explicitly name alternatives or conditions that would select another tool, but the verb/noun combination and the confirmation rule provide adequate usage 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 present, so the description must carry the behavioral burden. 'Fetch' unambiguously signals a read-only, side-effect-free operation, and the list of included data categories sets expectations for the response. It does not mention error/not-found behavior, but for a simple getter this is a minor omission.

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. It front-loads the core operation ('Fetch a single contact by id') before enumerating return contents, so every part 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 one-parameter getter with no output schema and no annotations, the description is largely complete: it names the input and the main output categories. It could be more explicit about response shape or not-found conditions, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% (id is described as 'Contact UUID'), so the baseline is 3. The description adds no parameter-level detail beyond saying 'by id,' which is already implied by 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 ('Fetch') and resource ('a single contact by id'), and enumerates returned data categories (tags, addresses, custom fields, recent activity). This clearly differentiates it from list/update/delete sibling tools even without naming 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?

The description establishes the obvious usage context: use this when you have a contact id and need one contact's full details. It does not explicitly name contacts_list or state when not to use it, but the 'single contact by id' phrasing is clear enough for selection.

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 burden of behavioral disclosure. It discloses the default limit of 50 and the ability to increase up to 200, noting a potential maximum discrepancy with the schema (which allows 1000). While it doesn't explain all side effects, the read-only nature is implicit, and it provides useful default behavior information.

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, concise and front-loaded with the purpose. The exception about limit is placed at the end, but still relevant. No fluff, every word contributes.

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

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

For a read-only list tool with no output schema, the description covers the primary purpose, usage context, and default behavior. Minor omissions like explicit mention of read-only or response format are covered by annotations being absent but the description is adequate. The limit discrepancy is a small gap but doesn't hinder core 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?

Schema coverage is 100%, so parameters are already documented. The description adds context by mentioning the default limit and the upper bound (200) which is not fully consistent with schema, and clarifies that search is free-text. This adds marginal value beyond the schema, justifying a score above baseline.

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

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

The description clearly states the tool lists the user's contacts with optional search and pagination, which is specific and distinguishes it from other contact operations (get/update/delete). It also mentions using it to summarize who's in the CRM, adding purpose clarity.

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 to use this before calling get/update/delete on a contact, and mentions summarizing the CRM. This provides clear when-to-use guidance and implicitly suggests it is not for individual contact retrieval or modification, differentiating from sibling tools.

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

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

With no annotations, the description carries the full burden. It discloses the key behavioral trait: omitted fields are left as-is, and passing an empty string clears a field (vs. omitting which keeps current value). This is critical for correct usage and goes beyond what the schema provides. It does not mention error behavior or auth, but the core mutation semantics are 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 two sentences with no filler. It front-loads the purpose and immediately follows with the essential behavioral note. Every word earns its place; no redundant information.

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

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

For a simple patch operation with 7 parameters and no output schema, the description covers the main pitfall (omission vs clearing). It does not mention error handling or response format, but these are often assumed for such tools. Given the low schema coverage and absence of annotations, it provides sufficient context for correct invocation, though it could optionally note what happens if the id is invalid.

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 14% (only 'id' is described). The description compensates by explaining the general rule for all fields: only include fields to change, and empty string clears. This provides crucial meaning beyond the schema's bare type declarations. It does not individually describe each parameter, but the names are self-explanatory and the patch semantics apply uniformly.

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 ('Patch'), a resource ('an existing contact'), and clarifies the partial-update semantics. It clearly distinguishes from contacts_create, contacts_delete, and contacts_get/list by indicating modification of an existing record.

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 purpose is clear: this tool updates an existing contact. It provides clear context for when to use it (to modify a contact) but does not explicitly mention alternatives or exclusions. The description does not say 'use this instead of create' but the verb 'patch' makes that implicit. No direct comparison to sibling tools, but the context 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?

With no annotations, the description carries the burden and does disclose a key behavioral outcome: the field becomes immediately available as a merge tag in email/SMS composers. It also mentions auto-generation of field_key. It doesn't cover uniqueness constraints or error behavior, but for a create tool this is reasonably transparent.

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

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

Three sentences, front-loaded with purpose and usage, then a note on field_key and a concrete behavioral result. Every sentence earns its place with no filler.

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

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

For a simple create tool with no output schema, the description covers what it does, when to use it, and a key side effect (merge tag availability). It doesn't mention the response format, but that's a minor gap given the tool's simplicity and the absence of an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal param-specific value: it repeats the auto-generation rule already in the schema and gives name examples, but doesn't clarify the semantics of options or entityType beyond what the schema already states.

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

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

The description clearly states the verb 'Define a new custom field' with the resources (contacts, companies, deals) and provides concrete examples of when to use it. It distinguishes from siblings by focusing on creation, and the examples (e.g., tracking loan amount) make the purpose unmistakable.

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

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

Explicitly instructs to use this tool when the user mentions tracking data without a built-in column, with examples. It also notes the auto-generation of field_key, guiding on when to provide it vs not. This gives clear when-to-use and implicitly contrasts with other custom field operations.

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 present, so the description carries the full burden. It explicitly discloses that all values on contacts/companies/deals are removed and that the action is irreversible, which is critical safety information for a destructive 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?

The description is two sentences with no filler. The main action is front-loaded, followed by the two most important consequences: cascade deletion and irreversibility.

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 single-parameter delete tool with no output schema and no annotations, this description provides everything an agent needs: what is deleted, what is also removed, and that it cannot be undone. Nothing critical is missing.

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

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

The input schema already documents the single 'id' parameter as a custom field UUID with 100% coverage. The description adds no further parameter-level information, so the schema baseline of 3 applies.

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

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

The description states a specific action and resource: 'Delete a custom field definition.' It clearly distinguishes this from sibling tools like custom_fields_create, custom_fields_update, and custom_fields_list by naming the delete operation and the cascade consequence.

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

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

The usage context is implied through the destructive wording, but the description never explicitly says when to use this versus related custom field tools, nor does it mention alternatives or conditions for non-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?

With no annotations, the description carries the behavioral burden. It clarifies that field_key is the identifier used in merge tags and custom_fields_set_value, which tells an agent how the output connects to other tools. The verb 'List' and the absence of mutation language signal a read-only operation.

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

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

The description is three sentences, front-loaded with the purpose and followed by a dense but useful enumeration of return fields and a clear usage cue. No filler is present, though the return-field list makes it slightly heavier than strictly necessary.

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 with no output schema, the description compensates well by enumerating the returned fields and their meanings, and by giving a concrete trigger condition. Pagination and empty-response behavior aren't mentioned, but they are minor gaps given the tool's low complexity.

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 single optional entityType parameter is fully documented in the schema with an enum and a clear description ('Optional — filter to fields on one entity type. Omit for all.'). Since schema description coverage is 100%, the description doesn't need to add parameter-level meaning; baseline 3 applies.

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

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

The description opens with a specific verb-object pair, 'List the user's defined custom fields,' and then enumerates the exact fields returned (field_key, name, type, options, entity_type). This clearly distinguishes it from mutation siblings like custom_fields_create/update/delete/set_value and from more general merge_tag 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?

The final sentence gives an explicit trigger: 'Call this before authoring email/SMS templates or workflows that reference custom field merge tags.' It doesn't name an alternative or state when not to use it, but the context is clear enough for an agent to select it.

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

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

With no annotations, the description carries the full transparency burden. It discloses key behaviors: it can set or update (implying overwrite), resolves values by field_key, and passing null clears the field. However, it does not mention permission requirements, whether the operation is idempotent, or what happens on invalid entity IDs or field keys. It's better than a bare mutation tool but not fully transparent.

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 compact and front-loaded: the core purpose is in the first sentence, followed by two illustrative examples and a critical caveat (null clears). Every sentence earns its place, and the structure guides the agent from what → when → how.

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 tool is a simple setter with no output schema and 100% schema coverage. The description covers the essential context: target entities, examples of use, a prerequisite call, and the null-clearing edge case. It doesn't address error handling or return values, but for this tool's complexity and scope, the description is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by giving concrete examples of values ('Hot', '$250k') and explaining that fieldKey resolution depends on the key naming convention (cf.lead_temp). It also reinforces the null-clearing behavior with a specific statement, tying parameter semantics to practical usage.

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

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

The description opens with a specific verb-resource pairing: 'Set or update a custom field value on a specific contact, company, or deal.' This clearly distinguishes it from sibling tools like custom_fields_create (which creates field definitions) and custom_fields_list (which lists available keys). The examples make the purpose instantly actionable.

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 'Use this when' and gives two concrete natural-language triggers (e.g., 'Casey is a Hot lead'), which tells an agent exactly when to invoke it. It also advises calling custom_fields_list first when the field keys are unknown. It doesn't explicitly name alternatives or when-not-to-use cases, but the examples and prerequisite provide strong practical 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses immutability constraints and a data-integrity rationale, but it does not explain side effects of replacing dropdown options on existing saved values, whether the update is partial, or what the tool returns.

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

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

Three short sentences are front-loaded with the primary action and immediately state constraints; there is no filler or repetition. Every sentence contributes useful selection or invocation 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 low complexity, 100% schema coverage, and the explicit immutability constraints, the definition is nearly complete for selecting and invoking the tool. It would be fully complete if it addressed the effect of replacing options on existing data and clarified the update semantics, since there are no annotations or output schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents id, name, options, and position. The description adds high-level meaning for name and options but adds no per-parameter detail beyond what the schema provides.

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

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

The description clearly states the operation ('Rename a custom field or change its dropdown options') and names an explicit resource, which distinguishes it from custom_fields_create/delete/set_value. It loses the top score because it omits the position-update capability from the high-level purpose, even though the schema includes position.

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

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

The description gives clear context for when this tool is appropriate and names an alternative for the immutability limits ('create a new field if you need either' for entity_type/field_key). It does not explicitly contrast with custom_fields_set_value or describe when not to use the tool for type changes, so it falls short of fully explicit when/when-not 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 must carry the behavioral burden. It explicitly discloses the output components, including the 30-day chart series, and the verb 'Get' plus 'summary' signals a read-only aggregation. It omits operational specifics like the exact definition of 'this period,' but for a parameterless summary call this is strong coverage.

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

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

Two concise sentences with no filler. The main KPI summary is front-loaded, and the 30-day series is added as a brief, clearly separated clause. 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?

For a parameterless dashboard-summary tool, this is nearly complete: it lists every KPI group and the charting series, so an agent knows what it will get. The phrase 'this period' is somewhat underspecified and there is no output schema, but the description is adequate for correct invocation and high-level interpretation.

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

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

The tool has zero parameters, so the schema provides no semantic burden and the baseline is 4. The description adds useful context about the scope of the summary ('this period') even though no parameters exist to modify it.

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?

Names a specific verb ('Get') and resource ('top-of-app KPI summary') and enumerates the contained metrics: total contacts, open deals with value, won deals with value, messages sent/received, and a 30-day series. This clearly distinguishes it from the many list/create/update siblings, none of which occupy the dashboard-summary role.

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

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

The description implies this is the tool to call when you need a dashboard-level KPI overview, but it does not explicitly state when not to use it or name alternatives for more granular data (e.g., campaigns_analytics or calls_list). There is clear context but no exclusionary 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?

With no annotations provided, the description carries the behavioral disclosure burden. It adds valuable non-obvious semantics: valueCents is in cents with a concrete example, and contactId/companyId can be used together. It does not mention return values or permission requirements, but the mutation behavior is clear from 'Create'.

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

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

Three tight sentences, each earning its place: the core operation, required fields, and critical parameter semantics. The most important information is front-loaded, and there is no redundant or filler language.

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

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

The description covers the essential non-obvious aspects: required fields, cent-based values, and relational linking. It omits return value details and behavior on invalid IDs, but the schema documents most remaining parameters, making this adequate for a create tool without an output schema.

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

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

Schema coverage is 63%, and the description compensates for undocumented parameters by explaining that contactId links to a contact and companyId links to a company, and both can be passed together. It also reinforces valueCents units with an example, adding meaning beyond the schema's 'Amount in cents'.

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

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

The description opens with 'Create a deal', a specific verb and resource that clearly distinguishes this from sibling tools like deals_get, deals_list, deals_update, and deals_delete. It also reinforces the core operation with required fields, leaving no ambiguity about what the tool does.

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

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

The description gives clear context for when to use the tool: creating a deal, with title and stageId as prerequisites. It does not explicitly mention alternatives like deals_update for modifying existing deals, but the create/update distinction is obvious from the tool name and siblings, so no exclusions are needed.

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 safety burden and at least states that this is a soft-delete and flags it as destructive. It does not disclose whether the action is reversible, what happens to related records, or whether special permissions are required.

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

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

The description is two short sentences with no filler: the operation comes first, followed by a clear safety warning. Every word contributes, and the caps signal importance without adding 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?

For a one-parameter delete operation with no output schema, the description contains the core behavioral fact and a confirmation warning, which is nearly complete. The only notable omission is whether soft-deleted deals can be restored, but this is a minor gap given the tool's simplicity.

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 exposes only a bare `id: string`, and the description supplies the essential link that the id identifies a deal. For a single required parameter this is sufficient, though the description does not say where the id should come from or validate its format.

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 precise operation, 'Soft-delete a deal,' naming both the verb and resource. The 'soft-' qualifier distinguishes it from a permanent delete and from sibling update/get/create tools, so an agent can select it correctly.

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

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

There is no guidance on when to use this instead of deals_update or another tool, and no statement about when a delete should be avoided. The 'DESTRUCTIVE — confirm first' warning implies caution but does not describe appropriate conditions or 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?

With no annotations provided, the description carries the behavioral disclosure burden. It adds useful context about the response contents (notes, tasks, linked contact/company), but does not disclose error behavior, auth requirements, or whether the returned data is fully hydrated. This is a reasonable but not deeply transparent 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?

The description is a single, front-loaded sentence with no filler. Every phrase contributes meaning: the operation, the resource, the id parameter, and the included related data.

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 get tool with no output schema, the description is nearly complete: it names the resource, the lookup key, and key return contents. It does not cover error handling or field formats, but those are less critical for a simple fetch operation.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented 'id' parameter. It only repeats that the tool fetches 'by id' without explaining the id format, source, or any constraints. The parameter name is self-explanatory, but the description adds little beyond the schema.

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

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

The description uses a specific verb ('Fetch') with a clear resource ('a single deal by id') and names the included related entities ('notes, tasks, and the contact/company linked'). This distinguishes it from siblings like deals_list and deals_create without needing to inspect 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 phrase 'a single deal by id' implies the primary use case and contrasts with deals_list, but it does not explicitly state when to choose this tool over alternatives or mention any exclusions. The usage guidance is present only by implication.

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 must disclose behavioral traits. It mentions returns all open+closed deals and fields, but does not disclose pagination behavior (limit/offset), default ordering, or potential performance implications. It also doesn't mention whether it returns only summarized fields or full objects. Given zero annotation coverage, 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?

The description is concise (two sentences) and front-loads the core purpose: 'List deals.' It then adds return fields and use cases efficiently. No filler, but it could be slightly more explicit about pagination. Still, it's well-structured.

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

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

The tool is relatively simple (list, no output schema), but with no annotations and 50% schema coverage, the description should cover more. It misses pagination details (limit/offset behavior), ordering, and any potential performance hints. For a list tool, it's adequate but not complete for an agent to understand all invocation nuances.

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 50%: the schema describes 'search' and 'stageId' but not 'limit' and 'offset'. The description does not explain limit/offset semantics, which are likely standard pagination but still undocumented. It adds minimal value beyond the schema; the 'filter by stage' hint reinforces stageId but doesn't clarify limit/offset, so a 3 is appropriate.

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

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

The description clearly states it lists deals and specifies the fields returned (stage, value, contact, company). It differentiates from sibling tools like deals_get (which retrieves a single deal) and deals_create/update/delete. However, it doesn't explicitly name those siblings, but the verb 'list' and resource 'deals' are specific enough.

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

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

The description provides clear use cases: 'summarize pipeline, find a deal to update, or filter by stage / value.' It does not explicitly mention when not to use it or contrast with alternatives, but the context is sufficient. The mention of 'filter by stage / value' implies the stageId and search parameters, which is helpful.

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 hints at per-user stage variability and the need to query stages, but does not disclose side effects (e.g., irreversible changes, downstream workflow triggers, error behavior on invalid stage IDs). For a mutation 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?

The description is two sentences with no filler. The core purpose is front-loaded, followed by a practical note on stage ID retrieval. Every word earns its place; it is compact and scannable.

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

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

For a simple two-parameter mutation with no output schema, the description covers the main prerequisite (knowing the stage ID) and hints at per-user variation. However, it omits failure modes (e.g., invalid deal ID, invalid stage ID), any effects on related entities (like pipelines or workflows), and whether the operation is reversible. These omissions leave gaps for an agent executing the call in a real workflow.

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 descriptions are clear ('Deal UUID', 'Destination stage UUID') and cover both parameters (100% coverage). The description adds value by explaining that stageId is not arbitrary—it must be a valid stage for the user—and provides common stage names as hints, plus a way to obtain correct IDs. This exceeds the schema's basic 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 action: 'Move a deal to a different pipeline stage.' It specifies the resource (deal) and the target (pipeline stage), which distinguishes it from siblings like deals_update (which likely handles other fields) and deals_create. The mention of common stage names adds specificity without ambiguity.

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 guidance on a prerequisite: 'call deal_stages.list first if you don't know the destination stage id.' This tells the agent when to use an alternative tool (deal_stages.list) before calling this one. It doesn't explicitly exclude deals_update for stage changes, but the dedicated action is clear. Slight deduction for not naming alternative mutation tools.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It goes beyond 'create a stage' by explaining that isWon/isLost mark terminal stages, exactly one of each should exist, deals in them stop counting as open, and omitting position appends to the pipeline. This is meaningful behavioral context, though it doesn't mention errors, permissions, or side effects on existing deals.

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 three sentences with no wasted words. The core action is front-loaded, and each subsequent sentence adds a necessary nuance (stage definition, terminal-stage rules, position behavior). 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 output schema and no annotations, the description covers the essential decision points: what the stage is, how to handle terminal stages, and how ordering works. It does not specify the return value or failure modes, but given the absence of an output schema and the relative simplicity of a create operation, this is a minor 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%, so baseline is 3. The description adds significant value beyond the schema: it explains that isWon and isLost are mutually exclusive terminal stage markers with a pipeline invariant, and clarifies that omitting position appends at the end. These are behavioral rules not present in the 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 opens with a specific verb and resource: 'Add a stage to the user's deal pipeline.' It also explains stages as columns in the pipeline, which clarifies the domain. Among sibling tools (deal_stages_list, deal_stages_reorder, deal_stages_update), 'create' is clearly distinct and unambiguous.

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

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

The description implies usage by defining the action and parameter behavior, but it never explicitly contrasts with sibling tools such as deal_stages_update or deal_stages_reorder. It gives actionable guidance on when to set isWon/isLost and when to omit position, but no when-not-to-use or alternative routing.

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

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

No annotations are provided, so the description carries the burden. It discloses the operation (listing, no mutation implied), the ordering ('in order'), and the returned fields ('name, color, position, and id'). For a zero-parameter read tool, 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?

Two concise sentences. The action and ordering come first, followed by a clear usage directive and return information. Every sentence earns its place with no filler.

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

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

For a simple, zero-parameter list operation, the description is complete: it states what is returned, the order, and when to use it. There is no output schema, but the return fields are explicitly named, so an agent knows what to expect.

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

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

The tool has zero parameters./coverage is 100%, and the baseline for 0-parameter tools is 4. The description adds no parameter details because none exist, so no deduction is warranted.

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

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

States a specific verb and resource: 'List the user's pipeline stages in order.' It is clearly distinguished from sibling tools like deal_stages_create, deal_stages_update, and deal_stages_reorder, which modify stages rather than list 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?

Explicitly instructs when to call the tool: 'Call this BEFORE creating a deal or moving one between stages so you have the correct stage UUIDs.' This gives an agent actionable timing and purpose, which is strong usage 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?

With no annotations, the description carries the burden of behavioral disclosure. It warns that a partial list leaves omitted stages in an undefined position, a key behavioral risk. It also implies a full replacement of order rather than incremental changes. While it doesn't mention auth or reversibility, the critical behavioral trait 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?

The description is two sentences with zero waste. The core action ('Reorder the pipeline') is front-loaded, followed by the critical instruction and 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?

For a simple reorder tool with a single parameter and no output schema, the description covers the core action, the required input format, the prerequisite for obtaining ids, and the risk of partial input. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100% and the schema already describes the 'ids' parameter as 'All stage ids, in the desired left-to-right order.' The description adds value by emphasizing 'EVERY stage id' and explicitly warning about the consequence of omission, which goes beyond the schema's terse 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?

The description opens with 'Reorder the pipeline,' a specific verb and resource that clearly states the tool's function. It distinguishes itself from siblings like deal_stages_list (listing) and deal_stages_update (updating a single stage) by focusing on reordering the entire stage sequence.

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

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

It provides a clear prerequisite: 'Get the current ids from deal_stages_list first,' guiding the agent on the necessary precondition. It does not explicitly name alternatives or exclusions, but the context (reordering vs. listing/updating) is clear enough for selection.

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 behavioral burden. It discloses a key non-obvious behavior: deals already on the stage keep their place, so the update only affects the label/color. It does not mention permissions or response shape, but the main risk of accidentally moving deals is explicitly addressed.

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 no filler. The first sentence states the primary action, and the second clarifies scope and non-move behavior, making it easy for an agent to parse quickly.

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 metadata update, the description combined with the fully documented schema covers the prerequisite and behavioral scope. It could have explicitly named sibling alternatives or described the return value, but those are minor gaps given the low tool complexity.

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 parameters are already fully documented. The description adds only the provenance of the id ('from deal_stages_list'), while name and color are self-explanatory from the schema. This matches the baseline for full schema coverage.

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

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

The description opens with a specific action, 'Rename or recolour an existing deal stage', identifying both the verb and the resource. It also differentiates itself from stage reordering or deal moves by stating it changes the label, not where anything sits.

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 clearly states the prerequisite: the id comes from deal_stages_list, and scopes the tool to existing stages. It does not explicitly name alternatives like deal_stages_create or deals_move_stage, but the 'existing' wording and the position-clarification imply when this tool is appropriate.

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 burden of disclosing behavior. It mentions that omitted fields remain unchanged, which is a useful hint, but does not disclose response format, validation rules, idempotency, or what happens if invalid data is provided. The mutation nature is implied but not explicitly stated.

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 extremely concise (two short sentences) with no filler content. It front-loads the main action ('Patch a deal') and adds a brief usage instruction. It is appropriately sized, though the brevity comes at the cost of completeness.

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 9 parameters, no output schema, no annotations, and zero schema description coverage, the description is severely inadequate. It provides no information about return values, error behavior, required fields (beyond schema), or any edge cases. An agent would struggle to call this correctly without additional external knowledge.

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 0% description coverage and the description offers no parameter explanations whatsoever. It does not clarify the format or meaning of fields like closeAt, valueCents, or stageId, leaving the agent to rely solely on parameter names and types, which may be ambiguous (e.g., valueCents units).

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 operation ('Patch a deal') and it is distinct from sibling tools like deals_create or deals_delete. However, it doesn't explicitly mention the resource type beyond 'deal' or differentiate from the specific deals_move_stage tool, but the verb 'patch' implies a partial update, which is reasonably clear.

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

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

The only usage hint is 'Only include fields to change,' which implies a partial update pattern but provides no guidance on when to choose this over alternatives like deals_move_stage for stage changes. No exclusions or alternative tool references are given, leaving the agent to infer usage 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 are provided, so the description carries the full burden. It discloses the exact fields returned, implying a read-only list operation. However, it does not mention any limitations, potential pagination, authentication requirements, or error cases. While the nature of a list tool makes some of these less critical, the lack of any behavioral nuance beyond the obvious keeps this at a moderate score.

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 with zero redundancy. The first sentence lists the tool's output, and the second provides cross-tool usage instructions. The most actionable information is front-loaded, and 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?

For a tool with no parameters and no output schema, the description is quite complete. It enumerates the return fields and explains how to use the id downstream. It lacks mention of edge cases like multiple mailboxes, but for a simple list operation this is adequate. The agent has enough information to call the tool and interpret results.

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

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

The tool has zero parameters, so the schema is empty and coverage is 100%. The description adds no parameter information because none is needed. The baseline for no-parameter tools is 4, and the description's extra context about the return fields does not detract from this.

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: 'List the user's connected mailboxes' and enumerates the specific fields returned (id, address, display name, provider, can-send flag, last sync). It also distinguishes itself from sibling email tools by explaining how the returned id feeds into email_send and email_list_threads, making the tool's role unmistakable.

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

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

The description provides explicit guidance on how to use the output: 'Use the id as `accountId` in email_send or as `account` in email_list_threads.' This tells the agent when to call this tool (to discover available mailboxes) and how to connect it to other operations. It does not mention when not to use it or alternatives, but for a simple list tool this is sufficient.

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 behavioral disclosure burden. It does well by explaining that bodies are fetched on demand and cached, that this call can be slower than list calls, and that attachment contents are never returned. It does not describe the response shape, but the core behavior is well covered.

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 three sentences with no filler. The primary purpose is front-loaded, followed by two caveats that each earn their place: the performance/caching behavior and the attachment exclusion. Every sentence contributes to correct invocation.

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

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

For a single-parameter tool with no output schema, the description is largely complete: it states what is returned (full body), the key limitation (no attachment contents), and the triggering condition (snippet insufficient). A brief note on the return format would make it fully complete, but nothing essential for invoking the tool 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 messageId already described as 'Message id from email_get_thread.' The tool description adds little parameter-level meaning beyond reinforcing that it refers to a single email message, so the schema does the heavy lifting and 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 opens with a specific verb and resource: 'Read the full body of ONE email message.' It clearly distinguishes this from the sibling list tools by emphasizing it handles a single message rather than a list, and the 'snippet' contrast implies the full content that list/thread tools truncate.

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 an explicit when-to-use rule: 'ask for it only when a snippet is not enough to answer the question.' It also points to the alternative category ('the list calls') and sets performance expectations, so an agent knows this is a targeted follow-up call rather than the default listing operation.

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 present, so the description carries the full burden of behavioral disclosure. It clearly states what is returned (sender, recipients, date, subject, snippet, attachment flag) and, importantly, what is NOT returned (bodies). This is sufficient for a simple read operation, though it omits minor details like error or empty-thread 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?

Three concise sentences with no filler: the main action and contents are front-loaded, the body-exclusion caveat follows, and the parameter source closes it. 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 single-parameter read tool with no output schema, the description fully covers what the agent needs: what comes back, what is omitted, the sibling tool to use for omitted data, and where the parameter comes from. Nothing essential is missing.

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

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

Schema description coverage is 100% and the schema already explains threadKey as 'From email_list_threads.' The description repeats this same information in prose, adding no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get every message in one email conversation' and enumerates the exact contents returned. It explicitly distinguishes itself from email_get_message_body by stating bodies are not included, which makes the tool's purpose unambiguous.

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

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

The description tells the agent when not to use this tool (when bodies are needed) and names the alternative: 'call email_get_message_body with a message id to read one.' It also provides the prerequisite relationship by stating the threadKey comes from email_list_threads.

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 behavioral disclosure burden. It clearly states what is returned, what is not returned (message bodies), and how to retrieve bodies. It lacks details on ordering or pagination, but for a read-only list operation the key behavior is well 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?

Three tightly written sentences: the main purpose and output are front-loaded, the key limitation is stated next, and parameter guidance follows. 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 simple list tool without an output schema, the description covers purpose, return fields, limitations, and relevant alternatives. It lacks explicit mention of ordering or pagination behavior, but this is a minor gap given the tool's low complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of `search` and `folder` but adds little beyond the schema's own parameter descriptions; `limit` and `account` are not elaborated further.

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 email conversations') and enumerates the returned fields: subjects, participants, dates, and a snippet. It also explicitly distinguishes itself from email_get_message_body by clarifying that it does not return message bodies.

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 when-to-use guidance: use email_get_message_body when a snippet is insufficient, and use `search` and `folder` to find or scope threads. This clearly routes an agent to the right operation and parameters.

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 burden of behavioral disclosure. It reveals side effects and defaults: signature appended automatically, message threads against a contact when contactId is passed, and messages leave from the oldest mailbox without accountId. These are meaningful behavioral traits beyond basic 'send an email' semantics, though it omits details like rate limits or error handling.

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 dense but every sentence earns its place: purpose, recipient syntax, body requirement, contact behavior, account selection, and signature note. It is front-loaded with the core action and immediately covers the most important parameter decisions. No filler or repetition exists.

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 12 parameters and no output schema or annotations, the description covers the critical decisions: recipient format, body requirements, merge tag handling, account selection, and signature behavior. It relies on the schema for details like cc/bcc and scheduling, which is acceptable since schema coverage is 100%. The picture is nearly complete, though error scenarios or expected return values are not described.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond parameter names. It clarifies that at least one of bodyHtml/bodyText is required, gives merge tag examples ({{first_name}}, {{cf.<field_key>}}), and explains that contactId does not pick the mailbox while fromEmail does not either. This helps an agent compose parameters 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 states a specific verb and resource: "Send an email from the user's connected email account." It clearly identifies the tool's action and adds concrete scope (recipient list, body formats, merge tags, account selection). It does not explicitly contrast against sibling tools like email_get_thread or email_list_threads, but the action is unambiguous.

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

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

The description provides clear usage context: when to pass contactId for merge tag resolution and threading, and when to call email_accounts_list and pass accountId to select a mailbox. It also states the default behavior when accountId is omitted. However, it does not explicitly mention when not to use this tool or compare it to alternatives, so it stops short of a 5.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description notes that placeholders are substituted at send time, which helps set expectations, and mentions the subject required, but it does not explain side effects (e.g., whether the template is immediately usable, any validation, or default behaviors). It lacks details on possible errors or the return format beyond the 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?

The description is concise and front-loaded with the core action. It uses two sentences to cover the main points: placeholders and required subject, ending with the return. There is little waste, though the first sentence could be slightly more explicit about the resource type for better scoping. Overall, it is efficient and readable.

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 the tool is simple (3 params, no output schema, no nested objects), the description is adequate. It covers the essential call details: placeholders, required subject, and return id. However, it lacks information about error handling, any side effects, or validation rules, which an agent might need in edge cases. The absence of annotations increases the need for such detail, so the description is minimally sufficient but not comprehensive.

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

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

Schema coverage is 100%, so the schema already describes each parameter (body, name, subject). The description adds value by specifying that subject is required and that placeholders are used, but does not go beyond the schema's own descriptions. Since schema coverage is high, baseline is 3, and the description provides marginal additional context (e.g., that variables are substituted automatically).

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

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

The description clearly states the action ('Create') and the resource ('EMAIL template'), and highlights that it is specifically for email templates, distinguishing it from SMS templates (sibling tools include sms_templates_create). It lists the required fields (subject) and placeholders, making the purpose precise and unambiguous.

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

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

The description does not explain when to use this tool versus alternatives like email_templates_update or sms_templates_create. It does not mention exclusions or prerequisites, such as needing an existing template or the context for email vs sms. The differentiation from SMS is implied by the resource name but not explicitly 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 provided, the description carries the full burden. It does disclose the destructive nature and indicates a soft-delete behavior, which adds value. However, it does not explain what soft-delete means, whether it is reversible, or what side effects occur.

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 extremely concise: two short sentences with the purpose front-loaded and the warning immediately following. Every word contributes meaning without filler.

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

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

For a destructive mutation with one parameter, the description still leaves important gaps: what the id refers to, what soft-delete implies, and what response the agent should expect. With no annotations or output schema, this is insufficient context for confident invocation.

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

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

The schema has 0% description coverage and the description does not mention the id parameter at all. The agent must infer from the tool name that id refers to a template identifier. No format, source, or validation guidance is provided for the only parameter.

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

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

The description states a specific operation ('soft-delete') and resource ('EMAIL template'), which clearly distinguishes it from sibling tools like sms_templates_delete or email_templates_update. There is no ambiguity about what the tool does.

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

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

The only guidance is 'DESTRUCTIVE — confirm first,' which is a caution rather than usage direction. The description does not explain when to prefer this tool over alternatives such as email_templates_update or email_templates_list, nor does it mention conditions where deletion should be avoided.

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 disclosing behavior. It only states that it fetches a template; it does not mention what is returned, error behavior for missing ids, read-only guarantees, permissions, or any response structure. For a tool with no output schema cont, 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?

The description is a single, front-loaded sentence with zero filler. It communicates the verb, resource, and parameter in a compact form. The uppercase 'EMAIL' efficiently disambiguates from non-email template tools. 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?

For a simple single-parameter getter, the description is minimally viable: it tells the agent what action to take and the required input. However, it lacks an output schema and does not describe the return format, so the agent has incomplete information about what to expect after invocation. This is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It names 'id' and associates it with the template, adding minimal context beyond the schema property name. However, it does not explain what the id is, where to obtain it, or any expected format. The meaning of the parameter is only partially clarified.

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 uses a specific verb ('Fetch'), a clear resource ('EMAIL template'), and a precise scope ('by id'). The explicit 'EMAIL' qualifier distinguishes it from SMS template tools, and the singular 'single' contrasts with email_templates_list. The purpose 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 context is implied: call this when you need one specific email template and have its id. However, the description does not explicitly state when not to use it, nor does it reference alternatives like email_templates_list or email_templates_get in other channels. The guidance exists but is only implicit.

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

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

No annotations are provided, so the description carries the burden. It discloses the scope ('user's templates') and the structure of each template, which is useful. However, it does not mention pagination, sorting, or explicitly state it is a read-only operation (though 'List' implies that). For a simple zero-parameter list tool, this is adequate but not exhaustive.

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 with no filler. The action is front-loaded, and the description efficiently conveys purpose, item structure, and a usage hint. 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?

Given the low complexity (no parameters, no output schema, no annotations), the description covers the essential facts: what the tool does, what it returns (templates with name, body, subject), and a typical use case. Minor gaps like pagination behavior are not critical for a simple list operation, so it is nearly 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?

The tool has zero parameters, so the baseline score is 4. The description does not need to explain parameters and does not add parameter-related info, which is appropriate. It mentions template attributes but those relate to the return value, not parameters.

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 'List' and the resource 'the user's EMAIL templates', distinguishing it from other template tools like email_templates_create, email_templates_get, and sms_templates_list. It also adds useful context about template contents (name, body, subject).

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 a specific use case: 'Use this to find an existing template before drafting a new one.' It implies this is the go-to for listing existing templates, but does not explicitly mention alternatives or when not to use it. It clearly establishes the primary purpose.

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 present, the description carries the full burden of behavioral disclosure, but 'Edit an existing EMAIL template' only conveys mutation. It does not state whether fields are partially updated, whether existing values are overwritten, what permissions are required, or what the tool returns after success.

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 a single, efficient sentence with the action and resource front-loaded. There is no filler or redundancy. It is slightly under-specified rather than padded, which is appropriate for the conciseness dimension even though it hurts completeness.

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 four parameters, no annotations, and no output schema, the description is too thin. It fails to explain update semantics, required id usage, whether body/name/subject are all editable in one call, or what the response looks like. An agent would need to infer most details from parameter names alone.

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 for the undocumented parameters, but it does not. The property names id, body, name, and subject are reasonably self-explanatory, yet the description adds no detail about which fields are updated, how body/subject/name interact, or the meaning of the required id.

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

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

The description uses a specific verb ('Edit') and a clear resource ('EMAIL template'), and clarifies it applies to an existing item, distinguishing it from create/delete/get siblings. It also signals the EMAIL domain, separating it from sms_templates_update. It could go further by naming the exact editable fields, but the core purpose 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?

No when-to-use guidance or explicit alternatives are provided. The phrase 'existing EMAIL template' implies this is not for creation, but the description never instructs the agent to prefer this tool over email_templates_create, email_templates_delete, or sms_templates_update in relevant scenarios.

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 burden of behavioral disclosure, and it does so thoroughly. It reveals that 'set_hours' and 'set_override' are mutations, that null clears values, that setting hours defines owner reachability in the account timezone, and that the get action returns a specific shape with mode_now reflecting immediate call routing. It also documents default behavior when no hours are set and the precedence of overrides.

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 information-dense, with every sentence contributing functional knowledge. It front-loads the core context of when the human answers versus Frontdesk, then follows a clear structure around the three actions. The compact notation and explicit caveat about the toggle demonstrate deliberate editing with no redundant or filler content.

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 absence of an output schema and annotations, the description is remarkably complete. It explains all return fields for 'get', all possible values of mode_now, the data format for setting hours, the clearing semantics, override precedence, and the toggle exception. An agent has enough information to select the right action Cherry and construct valid parameters without needing external documentation.

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 substantially enriches the schema's parameter definitions. While the schema explains the object shapes of 'hours' and 'override', the description adds day-key ranges (0–6, 0=Sunday), timezone context, the meaning of null to clear, the semantics of mode values 'emma' and 'me', and the behavior of expired overrides. It also explains exactly how the action parameter routes to each operation, which the schema leaves implicit.

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 identifies the tool's resource (frontdesk settings) and enumerates the specific actions it supports: reading current settings, setting owner hours, and forcing a mode until a deadline. It distinguishes the semantics of each mode ('emma', 'ring_then_emma', 'ring_then_voicemail') with concrete examples, leaving no ambiguity about what the tool does.

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 when-to-use semantics: when hours are set versus unset, when Frontdesk answers versus ringing the owner, how overrides take precedence, and that expired overrides are ignored. It also states a critical exclusion—none of this applies when the 'Frontdesk answers' toggle is off—so the agent knows the boundary of the tool's effect without needing to inspect sibling tools.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it flags create as returning the full URL with token exactly once and non-retrievable later, notes list/get omit the URL token, and states delete stops accepting POSTs immediately. It also discloses the signing secret header behavior. No contradictions with annotations exist.

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 longer than average but earned: it front-loads the resource definition, then organizes each mode into a scannable bullet, and the mappingJson example is dense but directly useful for the most complex parameter. There is no filler or tautological repetition.

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

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

For a nine-parameter router tool with no annotations and no output schema, the description covers all actions, required versus optional parameters, destructive behavior, and the one-time token retrieval caveat. Nothing an agent needs to invoke the tool safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the native-vs-mapped default decision, clarifying that signingSecret is optional and associated with X-Groundbase-Signature, and instructing that update should only include fields to change. It is not a 5 because several parameter behaviors (e.g., ipAllowlist empty meaning) are left to the already-sufficient schema rather than enriched.

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 definition names the resource ('inbound webhooks'), explains what they are ('URLs the world POSTs to so Groundbase creates contacts/deals/tasks/etc.'), and enumerates five concrete operations dispatched by `action`. This clearly differentiates the tool from the sibling outbound_webhooks_manage without needing to open 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?

Each action has an explicit when-to-use rule and prerequisites: list needs no args, get/update/delete require `id`, create requires `name`, and delete explicitly requires user confirmation. It also gives the mappingMode decision rule ('use mapped only when the sender has a fixed payload shape that needs translating'). This is strong enough to select the right operation and avoid mistakes.

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

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

Annotations are absent, so the description carries full burden. It discloses that currencies not listed in `prices` are converted from the base price at invoice time, a key behavioral detail. However, it does not mention the return value or that this is a persistent (reusable) object beyond 'reusable', nor any error conditions.

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 with no fluff; the key decision (use `prices` vs conversion) is front-loaded. It omits unnecessary details, though it could be more concise by dropping the parenthetical example, but overall well-paced.

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 7 parameters and no output schema, the description covers the trickiest part (currency handling) and leaves parameter details to the schema, which is rich (86% coverage). It's complete enough for an agent to call the tool correctly, though it could mention idempotency or reuse semantics.

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

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

Schema description coverage is 86%, and the schema already explains most parameters. The description adds clarity on the relationship between `unitPrice`, `baseCurrency`, and `prices`, which the schema lacks, but does not cover all nuances like the decimal-place rule for JPY (only in schema). Thus, a baseline 3 with marginal added value 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 opens with a specific verb and resource ('Create a reusable invoice item'), which clearly distinguishes it from its sibling list/update counterparts. It also explains the item's reusability, adding domain context beyond the name.

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 explains when to use `prices` versus relying on `unitPrice` and base currency conversion, giving direct guidance on a key decision. It does not explicitly state when not to use this tool versus alternatives, but the sibling context makes the create-only purpose clear.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the important semantic that each item may carry independently set prices per currency rather than converted values, but it omits pagination, ordering, filtering, and response shape. This is useful but incomplete.

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

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

The description is two sentences, front-loaded with the core action, and the second sentence earns its place by explaining a non-obvious pricing behavior with a concrete example. No wasted words.

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

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

For a parameterless list tool, this is largely complete: it states the resource and the key data behavior. It lacks explicit mention of pagination or exact return fields, but those are minor given no parameters and no output schema.

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

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

The tool has zero parameters, so the description cannot meaningfully add parameter semantics beyond the schema; the baseline 4 applies. It does clarify the data model that the returned fields represent.

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

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

The description clearly names the operation ('List') and the resource ('reusable invoice items') and adds a distinctive detail—per-currency prices—that separates it from invoice_items_create/update and invoices_list. Even without looking at the schema, an agent knows exactly what this tool returns.

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

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

It provides clear context that this is the read-only retrieval tool for reusable invoice items and explains the per-currency pricing model, so an agent can identify when it is relevant. It does not explicitly state exclusions or alternatives, but the sibling pairs (create/update/list) make the usage 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?

With no annotations, the description carries the burden and it does disclose the critical non-obvious behavior that `prices` is wholesale-replaced while omission preserves it. It also implies partial update semantics for other fields. It does not cover permissions, error cases, or response, but the main side-effect warning is present.

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 entire description is a single focused sentence, front-loading the operation and then adding the essential replacement caveat. No filler or repeated schema information.

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

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

For a 7-parameter tool with no annotations, no output schema, and 0% schema coverage, the description is under-specified. It addresses only the `prices` footgun and leaves the meaning of `unitPrice` vs `prices`, the required `id`, and tax/label/description fields to inference. An agent would likely need additional documentation to safely use all fields.

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