commsharbor

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

With no annotations, the description carries the burden of disclosing behavior. It clearly signals a create/write operation and the important limitation about allowlisted filter fields, but it does not mention permissions, failure behavior for invalid filters, duplicate names, or what the created resource 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?

Two sentences, no filler. The action is front-loaded, and the second sentence carries the single most important constraint. 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 create operation with no output schema and no annotations, the description leaves the filter structure, allowed field list, and response shape undefined. It is minimally sufficient because the schema covers required/optional parameters, but an agent still lacks concrete guidance for building a valid filter object.

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 filter constraint already present in the schema ('Allowlisted fields only') and adds the 'arbitrary query over the CRM' framing, but it does not meaningfully enhance the parameter docs.

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 opening sentence names a specific verb and resource: 'Create an audience or saved segment.' It identifies the two supported kinds (static, saved_segment) and is clearly distinct from sibling update/delete/get tools, which address different operations on the same resource.

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

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

The description does not name alternatives or state when to prefer this tool over audience_update or audiences, but it does give an operative constraint: only allowlisted filter fields are accepted, so a saved segment cannot be an arbitrary CRM query. That is useful context for deciding whether this tool fits, but not explicit selection 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 full burden of behavioral disclosure. It does disclose that the deletion includes memberships and leaves contacts untouched, which is useful. However, it does not mention permanence, required permissions, or any side effects beyond the audience itself, so transparency is partial.

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 extraneous words. The primary action is front-loaded, and the clarifying note about contacts follows immediately. It is highly efficient and well-structured.

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

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

For a simple delete operation with two well-documented parameters and no output schema, the description covers the essential behavior: what is deleted and what is not. It does not mention error handling or prerequisites, but those are minor for this 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?

Schema description coverage is 100%, so both parameters (audience_id and organization_id) are already documented in the schema. The description adds no additional parameter-level meaning, so the baseline score 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 clearly states the action ('Delete'), the resource ('an audience'), and the scope ('and its memberships'), while explicitly noting that contacts are untouched. This distinguishes it from sibling tools like create, get, and member_remove, and the 'contacts untouched' note clarifies it does not delete the underlying contacts.

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

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

The description implies when to use it (to delete an audience) but does not explicitly mention alternatives or when not to use it. It could have clarified that individual member removal should use member_remove instead, but the core usage is inferred from the clear action statement.

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. 'Read' indicates a non-mutating operation and 'one audience' limits scope, but the description does not say what data is returned, how missing audiences are handled, or any constraints beyond the organization scope.

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 word—'Read', 'one', 'audience', 'this organization'—earns its place and contributes to scoping the operation.

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 get with fully documented inputs, the description is minimally sufficient for selecting and invoking the tool. However, with no output schema and no mention of the returned audience structure or error behavior, the response shape is left entirely unspecified.

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 provides 100% coverage with clear descriptions for both parameters, so the baseline is 3. The description adds no parameter syntax or format details; it only reinforces that the audience belongs to the active organization, which matches the schema's 'Active organization ID' 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 uses a specific verb ('Read'), names the resource ('one audience'), and scopes it to 'this organization,' which distinguishes it from listing, creating, updating, or deleting audiences. Even without explicitly naming a sibling, the singular 'one' separates it from commsharbor_audiences.

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 'Read one audience' establishes the retrieval context clearly and implies this tool is for fetching a single audience rather than listing or mutating audiences. It does not explicitly name alternatives or say when not to use it, but the singular/read framing gives an agent enough context to choose correctly among the 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 provided, the description carries the burden of behavioral disclosure. It reveals the important static-only constraint, but it does not disclose side effects, such as whether duplicate memberships are prevented, whether the contact must already exist, or what happens on failure. The static-audience nuance adds value, but the mutation behavior remains under-described.

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 tight sentences with no filler. The primary action is stated first, and the critical scope restriction follows immediately. 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 three-parameter endpoint with full schema coverage, the description is nearly complete: it explains the action, the target resource, and the key limitation about static audiences. Minor gaps remain around idempotency and error behavior, especially since there is no output schema to clarify expected 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?

Schema description coverage is 100 percent, so the schema already documents all three parameters as IDs. The description adds no additional meaning about how the parameters interact or what valid values look like, so 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 uses a specific verb and resource: 'Add a CRM contact to a static audience.' It also distinguishes this tool from sibling audience tools by explicitly scoping it to static audiences, so an agent can tell it apart from audience_create or member_remove without guessing.

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 states when to use this tool ('Only for static audiences') and when not to use it ('a saved segment's membership comes from its filter, not from this route'). This gives clear exclusion criteria and prevents misuse on segment-managed audiences.

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 not state whether the contact is permanently removed, whether the operation is idempotent, what happens if the contact is not in the audience, or any side effects. The word 'Remove' implies mutation, but the actual behavior is not detailed enough for an agent to understand the consequences.

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, concise sentence that uses minimal words. It is appropriately sized and front-loaded with the action. It lacks additional detail but does not waste words, so it earns a 4 for conciseness and structure.

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

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

Given the tool's simplicity (3 required parameters, no output schema, no annotations), one might expect a higher score, but the description is still incomplete. It does not mention prerequisites (e.g., the audience must exist, the contact must be in the audience), the result (e.g., success or error messages), or any caveats like the difference between static and dynamic audiences. An agent can call it correctly from the schema, but it lacks important contextual details.

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 description coverage is 100% and all three parameters have descriptive names and brief descriptions (e.g., 'CRM contact ID', 'Audience ID', 'Active organization ID'). The description adds no further meaning beyond these, so the baseline of 3 is appropriate. However, it does not clarify the relationship between audience_id and contact_id or clarify what 'Active organization ID' means in the context of removal.

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 'Remove a contact from a static audience' clearly states the action (remove) and the resource (contact from audience). It differentiates from sibling tools like 'add' and 'members' by indicating removal, but does not explicitly contrast with the sibling 'audience_member_add' or clarify 'static audience', which could be ambiguous against dynamic audiences.

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 provide guidance on when to use this tool vs. alternatives. There is no mention of when removal is appropriate, whether it is reversible, or how it relates to the audience member add tool. An agent might need to infer that this is the inverse of 'audience_member_add' but that is not 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 must carry the behavioral burden. It clearly conveys a read-only snapshot of current audience membership, but it does not disclose pagination behavior, result shape, or behavior for invalid or missing audience IDs.

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 focused sentence with no filler. The core action and resource are front-loaded, making it appropriately sized for the tool's simplicity.

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 identifies what the tool returns conceptually (contacts in an audience), and the schema covers required parameters and pagination. It is slightly thin on result shape and pagination behavior, but for a low-complexity read/list tool this 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?

Schema description coverage is 100%, and the schema already documents each parameter, including cursor as an 'Opaque pagination cursor' and limit as 'Page size, maximum 100'. The description adds no additional parameter semantics beyond the audience/contact context.

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 ('contacts currently in one audience'), making the tool's purpose clear. It distinguishes itself from sibling tools like commsharbor_audiences (listing audiences) and member_add/remove (mutating membership), though it does not explicitly contrast with commsharbor_audience_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?

Usage is implied: call this tool when you need the current contacts in a specific audience. However, there is no explicit when-not guidance or routing to alternatives such as commsharbor_audience_get, so the context 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 full burden of behavioral disclosure. It only states the read operation 'List' and does not mention pagination behavior (despite cursor/limit parameters), result ordering, or the distinction between static audiences and saved segments. This leaves significant behavioral traits undisclosed.

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. It efficiently communicates the core action and resource, fitting the minimal structure expected for a simple list tool.

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

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

The tool has a fully documented schema and no output schema, so the description need not explain return values. However, it does not clarify what differentiates 'static audiences' from 'saved segments' or explicitly note the paginated nature of the response, leaving some context for the agent to infer from the parameters.

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

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

Schema description coverage is 100%, so all parameters (organization_id, limit, cursor) are documented. The description adds no additional parameter-level meaning, such as how 'static audiences' relates to the query or when to use cursor. Baseline 3 is appropriate given the high 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 'List static audiences and saved segments' clearly specifies the verb (list) and resource (audiences and saved segments). It distinguishes this from sibling tools like commsharbor_audience_get (singular fetch) and commsharbor_audience_members (list members), though it does not explicitly name 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 use case is implied by the verb 'List' – use this to retrieve a collection of audiences. However, there is no explicit guidance on when to choose this over siblings, such as commsharbor_audience_get for a single audience, or mention of prerequisites beyond the required organization_id.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It names the mutation ('rename' or 'change saved filter') but does not explain whether the update is a partial or full replacement, what happens to existing audience references, whether validation errors can occur, or what the response looks like. This is a meaningful 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 a single efficient sentence with no filler. It clearly lists the two supported update operations and is 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?

Given no output schema and no annotations, the description is too thin for a mutation tool with a nested filter object. It omits usage context, side-effect transparency, and any indication of success or failure behavior, so an agent gets only the bare minimum needed to understand the action.

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%: name, filter, organization_id, and audience_id all have descriptions. The tool description adds no significant parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: rename an audience or change its saved filter. It clearly distinguishes this tool from siblings like create, delete, get, and member operations, so an agent can identify what it does at a glance.

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

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

Usage is implied by the description—modify an existing audience's name or filter—but there is no explicit guidance about when to use this tool versus alternatives like commsharbor_audience_create or commsharbor_audience_delete. No exclusions or alternative recommendations are 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 provided, the description carries the behavioral disclosure burden. It adds useful context: 'Audit records are never rewritten and never carry recipient PII,' implying immutability and privacy. However, it does not explicitly confirm the operation is read-only, nor does it mention pagination behavior, ordering, or authorization 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?

The description is two sentences with no filler. The primary purpose is front-loaded, and the additional behavioral notes are concise and relevant. Every sentence contributes value.

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

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

For a low-complexity list operation with two parameters and no output schema, the description is minimally sufficient. It lacks details on how to use the cursor for pagination, what fields the returned audit events contain, and any ordering or time-range constraints, which would help the agent fully understand the tool's behavior.

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

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

Schema description coverage is 100% — both parameters have descriptions ('Opaque cursor' and 'Active organization ID'). The tool description adds no additional parameter meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'List tenant audit events.' It identifies a specific, distinct resource that no sibling tool explicitly appears to cover, but it does not explicitly differentiate itself from other event-listing tools like commsharbor_delivery_events.

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 guidance on when to use this tool versus alternatives, nor does it mention any exclusions, prerequisites, or context such as compliance or security review scenarios. The agent must infer usage solely from the tool name.

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

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

With no annotations, the description carries the burden. It discloses the read-only nature ('Read') and adds behavioral context by explaining the state fields (active, warning, started) and trial behavior, which helps the agent interpret the response. Does not mention side effects or errors, but for a simple read 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?

Two sentences, front-loaded with the core purpose, then specific guidance on key fields. No wasted words; every sentence adds value.

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

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

Although there is no output schema, the description explains the key response fields (state.active, state.warning, state.started) that the agent needs to make decisions. It doesn't enumerate every field, but the essential ones for the stated use case are covered, making the tool usable.

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 parameter (organization_id) is fully described in the schema ('Active organization ID') with 100% coverage. The description adds no additional parameter meaning, 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?

The description clearly states the tool reads the organization's plan, limits, and global entitlements. It distinguishes itself from siblings like commsharbor_billing_catalog (catalog) and commsharbor_billing_purchase (purchase) by focusing on the read-only billing status.

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 read before a bulk send and explains the meaning of state.active and state.warning, giving a clear when-to-use directive. Does not mention alternatives or when not to use it, but the context is sufficient for this read 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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly states the operation is read-only and unauthenticated, which are the key behavioral traits an agent needs. It does not describe response shape or freshness, but for a zero-parameter public catalog 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 a single sentence with the core action front-loaded. The second clause is rationale rather than tool behavior, but it is brief and adds decision-relevant context without becoming bloated.

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

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

For a simple public catalog with no parameters and no output schema, the description provides the essential expectations: no authentication, read-only behavior, and what data is returned. It could mention that no arguments are required in prose, but the empty input schema already conveys that.

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 properties, so there are no parameter semantics to document. The description confirms the tool can be called freely without inputs, matching the baseline for a no-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 states a specific verb ('Read') and a concrete resource ('plans, prices and x402 network'), and adds that it is public and unauthenticated. This makes the tool's purpose clear, but it does not explicitly differentiate it from sibling tools like commsharbor_billing or pricing.

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 clear use case: learn costs before deciding whether to sign up. It also clarifies that no authentication is needed. It does not explicitly discuss exclusions or alternative tools, but the context is strong enough for an agent to know 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?

With no annotations provided, the description carries the full burden, and it does so richly: it discloses the 409 checkout_disabled response, the 402 flow with accepts[], the two payment doors (cred token and X-PAYMENT), entitlement durations, stacking behavior, and idempotency safety. This is far beyond what the schema reveals.

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 and every sentence earns its place, front-loading the core purchase action and payment door. However, it runs long and uses jargon like 'x402' that mildly hurts readability; a little more explicit structure would push it to a 5.

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

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

For a 3-parameter tool with no output schema and no annotations, the description is remarkably complete: an agent knows the main success path, the failure modes, payment mechanisms, retry semantics, and what constitutes a valid purchase. Nothing essential for selecting or 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains what 'pass' versus 'topup' entails (30 vs 365 days, stacking, active-pass requirement) and that the idempotency_key makes credit retries safe. This lifts it 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 opens with a specific verb and resource: 'Buy a pass or top-up'. It also states the payment method ('credit or x402') and the global entitlement outcome, distinguishing it clearly from related tools like commsharbor_billing_catalog and commsharbor_billing.

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 using the tool: it is for purchasing a pass or top-up, with explicit behavior when checkout is disabled versus enabled. It does not explicitly name alternatives or state when not to use it, so it falls just 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?

With no annotations, the description must carry the full burden. It discloses a key behavioral constraint (dependencies on verified domain and published template) but omits other critical traits: what the response contains (e.g., campaign ID), error behavior, and any side effects. It is a write operation, but that is inferred from 'Create,' not stated. The single constraint is useful but insufficient for a mutation tool with no output schema.

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

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

Two sentences with no filler. The main purpose is front-loaded, and the prerequisite constraint is stated succinctly. 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 creation tool with 6 parameters and no output schema, the description is thin. It does not mention the optional template_version parameter or what the success response looks like. An agent would not know whether the draft ID is returned or how to reference it later. Given no annotations and no output schema, 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?

Schema coverage is 100%, so parameters are fully documented. The description adds no new parameter-level information beyond the schema; it reiterates that domain and template must be active/published, which the schema already states. Thus it meets the baseline but adds minimal extra 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 the action ('Create a campaign draft') and specifies the resource type. It differentiates from siblings like campaign_launch and campaign_update by emphasizing 'draft.' The prerequisite mention further clarifies scope.

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 implies when to use it (to create a draft) but does not explicitly contrast with alternatives such as campaign_launch or campaign_update. It provides context that the draft cannot be created against unverified domains or unpublished templates, which is a usage constraint, but it does not name sibling tools or state when not to use it.

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

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

With no annotations, the description must carry the behavioral transparency burden. It states the operation is a read and explicitly excludes recipient data, which is useful. However, it does not disclose output shape, error behavior, or auth requirements, though these are less critical for a simple read.

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 with no filler, and the core action and scope are front-loaded. 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 low-complexity two-parameter read operation, the description and schema together cover invocation well. The key exclusion ('without any recipient data') is explicitly stated. A return-value description is missing, but the simplicity of the operation makes this 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 description coverage is 100%, and both parameters have clear descriptions in the schema. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Read') and resource ('one campaign'), and adds a critical scope qualifier ('without any recipient data'). This clearly distinguishes it from sibling tools like campaign_report or campaigns that would return aggregate or recipient-level information.

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 'without any recipient data' implies when this tool is appropriate versus a more data-rich alternative, but it never names an alternative or states explicit when-to-use/when-not-to-use conditions. The intended context is inferable but not stated.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It thoroughly explains idempotency (replaying the same key returns the same campaign and produces no second dispatch), the one-time freeze, and that consent, suppressions, and audience membership are evaluated at freeze time. This goes well beyond a basic 'launches a campaign' and gives the agent a clear mental model of side effects and guarantees.

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, each earning its place. The main action is front-loaded, followed by the critical freeze behavior and the idempotency guarantee. No fluff or repetition; every clause adds value.

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

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

For a launch tool with no output schema, the description covers the essential behaviors: idempotency, freeze timing, and what gets sent. It does not mention error cases (e.g., campaign not found, invalid state) or required preconditions (e.g., campaign must exist), but these are often expected to be handled generically. The freeze and idempotency details are sufficiently complete for an agent 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 coverage is 100%, so parameters already have descriptions. The description adds meaningful context for the idempotency_key by explaining its replay semantics (returns same campaign, no second dispatch) and clarifies that scheduled_for controls scheduling versus immediate launch. This goes beyond the schema's one-line descriptions and enriches understanding, though it does not enumerate each parameter explicitly.

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: 'Freeze and launch or schedule a campaign idempotently.' It clearly states what the tool does (launches or schedules a campaign) and distinguishes it from sibling tools like campaign_create (creation), campaign_get (retrieval), and campaign_update (modification). The freeze semantics add specificity, leaving no doubt this is the launch action.

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

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

The description implies when to use this tool (when launching or scheduling a campaign) but does not explicitly contrast it with alternatives or state conditions like 'use this instead of campaign_update' or prerequisites such as the campaign must exist. The 'launch or schedule' wording covers both immediate and delayed dispatch, but there is no explicit guidance on choosing between them beyond the scheduled_for parameter. This is adequate but not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool returns only counts, not individual-level data, which is a key behavioral trait. It also implies read-only behavior by describing a reconcile/aggregate function. While it doesn't mention side effects or permissions, the disclosure of output scope is valuable and exceeds a baseline.

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 sentences that front-load the purpose and immediately clarify the limitation. Every word earns its place, and there is no fluff or redundancy. It is appropriately sized for a simple tool.

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

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

Given the tool's simplicity (two required parameters, no output schema), the description adequately conveys what the tool does and what it returns. It clarifies the scope and the nature of the output (counts only). It doesn't mention prerequisites or errors, but for a read-only report tool this is sufficient. A 5 might be warranted if it specified return structure or error cases, but it's not 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 covers both parameters with descriptions ('Campaign ID' and 'Active organization ID'), achieving 100% coverage. The tool description adds no additional meaning beyond that, so it does not elevate beyond the baseline. It doesn't clarify formats, relationships, or usage nuances for the 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 tool's purpose with the verb 'Reconcile' and the resource 'campaign deliveries and feedback.' It also explicitly distinguishes this tool from any that would provide per-person open details, which helps differentiate it from sibling tools like commsharbor_delivery_events or commsharbor_campaign_get. The scope 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 context on when to use this tool: when aggregate counts are needed. It also gives an explicit exclusion: 'Which specific person opened what is not something this API answers,' which tells the agent this tool is not suitable for individual-level queries. However, it does not name alternative tools for that need, so it falls slightly 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 bears the burden of conveying behavior. 'List' correctly suggests a read-only, non-mutating operation, but the description does not disclose pagination, ordering, result shape, or any limits.

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

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

The description is a single, concise sentence with no filler. Every word contributes to meaning, and the key action and scope are front-loaded.

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

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

For a simple list operation with a single fully described parameter, the description is adequate but minimal. It does not mention pagination, filtering, or return value expectations, which would help an agent fully understand the tool's behavior.

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

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

Schema coverage is 100% and the only parameter, organization_id, is described as 'Active organization ID'. The description adds little beyond reinforcing the organization scope, so the schema is carrying the semantic weight.

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 ('campaigns') and scopes the operation to the organization. It clearly conveys a collection-reading operation, though it does not explicitly differentiate itself from sibling tools like commsharbor_campaign_get or commsharbor_campaign_report.

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 tool is for listing all campaigns, and sibling names suggest alternatives for single-campaign or campaign-specific operations. However, there is no explicit guidance about when to choose this over related tools or any 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?

With no annotations, the description carries the behavioral disclosure burden. It goes beyond a simple 'update' by explaining the freeze semantics for the recipient set and template version after launch, which is valuable state-change information. It does not mention auth, error cases, or response details, but the core behavior is 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?

Two tight sentences with no filler. The action list is front-loadedaging, and the important lifecycle constraint follows immediately. 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?

The description gives the key lifecycle logic but omits some context needed for confident invocation: the exact status mapping for pause/resume/cancel, any state-transition validation rules, and the response shape (no output schema). The sibling campaign_launch tool could be referenced to clarify the launch boundary. These gaps make it functional yet 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?

The input schema describes all eight parameters with 100% coverage, so the baseline is 3. The description adds useful context around template_version and draft-only content changes, but it does not resolve the inconsistency between the status enum ('paused', 'sending', 'cancelled') and the schema description saying 'paused, running or canceled'. It provides no additional parameter meaning beyond the schema.

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

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

The description states a specific set of actions—edit, pause, resume, or cancel—applied to a campaign, with the resource clearly identified. It also distinguishes itself from launch/create/get siblings by focusing on post-create state and content updates.

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 explains the main usage constraint: content changes are only possible while the campaign is a draft, and after launch only state transitions occur. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for an agent to route correctly.

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 adds meaningful behavioral context: files expire after 7 days and that durable audit and row-level results persist beyond the file. This goes beyond a simple 'download' and helps set expectations about the data's lifecycle, though it does not explicitly state the operation is read-only.

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

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

Two concise sentences with the primary action front-loaded. Every phrase adds value: the action, the expiry warning, and the persistence note. No fluff or 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 simple download tool with only two parameters and no output schema, the description covers the essential context: the file type, expiration, and what data persists. It does not describe the response format, but that is likely self-evident for a file download. Minor omission given the 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 coverage is 100% and both parameters (file_id, organization_id) are already described. The description adds no additional semantic detail about the parameters, so it meets the baseline but does not enhance understanding beyond the schema.

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

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

The description clearly states the action 'Download a tenant CSV' with a specific resource, but does not explicitly differentiate from sibling download tools like commsharbor_data_export_download or commsharbor_contacts_export. The 'tenant' qualifier is slightly ambiguous but the intent is clear 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?

It provides contextual guidance ('before expiry') and explains the 7-day expiration, but it does not mention when to avoid this tool or name alternative tools. There is no explicit routing, so an agent might not know this is the right download for contact files specifically.

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

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

With no annotations, the description carries the full burden, and it does well by disclosing the key behavioral trait: reusing the idempotency key returns the same import and never creates a second Queue message. It leaves some behaviors unspecified (e.g., error handling or what confirmation triggers), but the most important side-effect is clearly 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 short and front-loaded, with the core action in the first sentence. It could be slightly tighter because 'mandatory idempotency key' is repeated as 'The idempotency key is mandatory here,' but the overall structure 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 a simple three-parameter tool with no output schema, the description covers the essential invocation context and the one behavioral nuance that matters for correct use. It does not describe the response format or failure modes, but nothing critical is missing for an agent 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for idempotency_key beyond the schema's 'Unique confirmation key' by explaining that reuse returns the same import and prevents duplicate Queue messages. It adds nothing new for import_id or organization_id, but their schema descriptions are sufficient.

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

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

The description states a clear action ('Confirm an import') and a specific resource with a notable constraint (mandatory idempotency key). It distinguishes this tool from sibling read/preview operations like contact_import_get and contact_import_preview, though it does not name them explicitly.

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

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

The description gives clear context: this tool is for confirming an import and requires an idempotency key, with reuse returning the same import. It explains the practical reason for the idempotency requirement (avoiding duplicate imports on retry) but does not explicitly contrast it with alternatives or state when not to use it.

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

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

With no annotations, the description carries the behavioral disclosure burden. It communicates a read-only list operation and adds that results are row-numbered per import, but does not address pagination behavior, response contents beyond row numbers, or other operational details. The verb 'List' signals safety, yet the description is otherwise minimal.

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

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

One compact sentence with no filler; the key facts (list, row-numbered errors, one import, purpose) are front-loaded and every phrase 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 paginated list tool with fully documented parameters, this is mostly complete: the agent knows the required identifiers, the pagination knob, and the purpose. The main gap is the lack of an output schema or a statement of what fields each error entry contains, but 'row-numbered errors' provides enough to call and interpret the tool at a basic level.

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 describes all four parameters completely ('Page size, maximum 100', 'Opaque pagination cursor', 'Contact import ID', 'Active organization ID'). The description adds only a general context of row-numbered errors and does not elaborate parameter usage, so it is at the 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 uses a specific verb ('List') and a specific resource ('row-numbered errors of one import'), and attaches a clear purpose ('so the source file can be fixed'). It is immediately distinguishable from siblings like contact_import_preview or contact_import_get because it is explicitly about error rows for a single import.

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 clause implies the intended use—when an import produced row-level errors that need correction in the source file. However, it does not explicitly state when not to use it or name alternatives, so the agent has to infer the tool-selection boundary.

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. It discloses that this is a read operation and returns current counts, which implies non-mutating behavior. However, it does not mention any other behavioral aspects (e.g., whether it includes errors, if counts are live, or any auth requirements). This is a minimal but adequate disclosure for a simple get 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 a single, front-loaded sentence that immediately states the core purpose. It is concise with zero wasted words, and the key information (read, single import, counts) is presented upfront.

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 get operation with two well-documented parameters, the description is largely complete. It specifies the returned data (counts) and the action. Minor gaps include not clarifying what 'durable' means or what exactly the counts include, but these are not critical for an agent 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%, with both parameters documented (import_id and organization_id). The description does not add any meaning beyond the schema, so the baseline of 3 is appropriate. No extra clarification or format details are provided.

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 (Read) and the resource (one durable contact import) plus what is returned (current counts). It is specific and distinguishes from siblings like confirm, errors, preview, and imports by focusing on reading a single import with counts.

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

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

No guidance is provided on when to use this tool versus its siblings (confirm, errors, preview, imports). The description only states what it does, not the conditions that would select it over alternatives. Given the large sibling list, explicit routing would help.

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

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

With no annotations provided, the description carries full behavioral disclosure burden. It explicitly states the most critical side-effect ('Nothing is created by this call') and the mandatory consent declaration, adding meaningful behavioral context beyond the schema. It does not mention return values or follow-up behavior, but these are less critical for a preview 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?

Three sentences with the key action front-loaded. The third sentence, while memorable, is slightly long-winded ('an import that cannot say why these people may be emailed is an import that does not happen') and could be tightened to 'The consent declaration is mandatory.' Overall, it is concise and well-structured.

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

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

The tool has 6 required parameters and no output schema, so the description should clarify what the preview returns or how to follow up (e.g., calling commsharbor_contact_import_confirm). It does not mention return values, error handling, or next steps, leaving an important gap for an agent deciding whether to proceed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema; it merely reinforces the consent-related parameters ('consent-declared CSV') without explaining individual params. The schema already handles parameter semantics effectively.

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: 'Upload and preview a consent-declared CSV.' It further clarifies the non-mutating nature with 'Nothing is created by this call,' which distinguishes it from sibling tools like commsharbor_contact_import_confirm. This is a clear, specific, and non-tautological purpose.

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 'preview' and the explicit statement 'Nothing is created by this call' provide clear context that this tool is for pre-flight validation rather than final import. However, it does not explicitly name alternatives (e.g., 'use commsharbor_contact_import_confirm to actually import'), 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'List', which implies a read operation, but it fails to mention pagination (despite the cursor parameter), response format, or any other operational behavior. The description does not contradict annotations (there are none), but it is dangerously underinformative.

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, concise sentence that front-loads the action and resource without any filler. Every word earns its place, and it is appropriately sized for a list operation with minimal complexity.

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?

Even for a simple list tool, the description is incomplete. It does not explain that results are paginated via the cursor, nor does it describe the output shape. Since there is no output schema, the agent has no guidance on what to expect in the response, making the description insufficiently complete for a tool with pagination.

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 provides complete descriptions for all three parameters (organization_id, limit, cursor) with 100% coverage. The description adds no new meaning—'of the organization' merely echoes the schema's organization_id description. Thus, the schema does the heavy lifting, and the description contributes nothing extra.

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 (List) and the resource (contact imports) with an explicit scope (organization). It differentiates from sibling tools like commsharbor_contact_import_get by being plural and implying a collection listing, making it immediately distinguishable.

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 a clear use case: list all contact imports for the organization. However, it does not explicitly state when to avoid this tool or mention alternatives such as commsharbor_contact_import_get for retrieving a single import, leaving the choice largely 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?

With no annotations provided, the description carries the full burden. It clearly states the operation is a read, implying no side effects, and adds domain context about where permission lives. However, it does not disclose response shape, error behavior, or any special conditions around consent/preference data. 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 short and front-loaded with the action. The two follow-up sentences add meaningful context about the consent concept rather than fluff. Slight redundancy between 'Being in the CRM is not permission to email' and 'This resource is where permission actually lives' keeps it from being a perfect 5.

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

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

The tool is simple with two fully described parameters, and the description conveys the core domain concept. But with no output schema and no annotation coverage, an agent does not learn what the response will contain or how preferences are represented. This is a minor gap for such a simple read, but it prevents a higher score.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds no additional parameter-level meaning beyond identifying what the resource represents. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a specific verb and object: 'Read consent and preference for a CRM contact.' It identifies the exact resource and clarifies that this is the permission source, distinguishing it from general CRM contact reads. The warning 'Being in the CRM is not permission to email' reinforces that this tool serves a distinct purpose.

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 the usage context clear: use this tool when you need the actual consent/preference record for a contact. It also provides a strong exclusion signal by warning that CRM membership alone is not permission. However, it does not explicitly name alternative sibling tools such as commsharbor_crm_contacts_get or commsharbor_preference_get.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers the most important safety-critical trait: recording consent NEVER restores a previous unsubscribe, and marketing_enabled remains false for opted-out contacts. This prevents a serious misuse that an agent could easily make.

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 with no wasted words. The primary purpose is front-loaded, and the critical caveat follows immediately. 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?

Given fully documented parameters, no annotations, and no output schema, the description covers the central safety context an agent needs. It is slightly incomplete in that it does not mention response behavior or explicitly contrast with related marketing/suppression tools, but it is nearly sufficient for the tool's 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 parameters are already documented in the input schema. The description adds no parameter-level nuance, though it does reference the marketing_enabled field, which is not part of the input schema and helps explain the tool's effect.

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 ('Record permission-based marketing consent') on a defined resource, and immediately clarifies the tool's role versus a generic consent toggle. The explicit warning about not restoring an unsubscribe makes its purpose unmistakable even among many sibling 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?

It gives clear when-to-use context: record permission-based consent. It also states a critical when-not-to-use case: do not use it to restore a previously opted-out contact. It does not explicitly name alternative sibling tools such as contact_marketing_get or suppression_create, so it stops short of full 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?

The description mentions that the export is 'retained for seven days,' which is a useful behavioral detail beyond the schema. However, it does not disclose other important aspects like the format details, whether the export is synchronous or asynchronous, or how to retrieve the output. Since no annotations are provided, the description carries the burden, but it only partially covers behavior.

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

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

The description is a single, concise sentence that front-loads the action and resource, with a brief retention detail. Every word contributes meaning with 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?

The tool is fairly simple with one parameter and no output schema, so the description is almost adequate. However, some context is missing: what to do after the export is created, how to access the file, and the format (CSV) is stated but no link to retrieval tools. Given the simplicity, a 3 seems right; more could be added about retrieval 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?

The input schema fully describes the only parameter (organization_id) with a description, reaching 100% coverage. The description adds no additional semantic value beyond the schema, so a 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 states a clear verb ('Create') with a specific resource ('CSV export of the organization's contacts'), which is distinct enough from the sibling tools like commsharbor_contact_import_* or commsharbor_crm_contacts_*. It does not mention any alternative or differentiate explicitly, but 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 guidance on when to use this tool versus other export-related tools such as commsharbor_data_export_create or commsharbor_contact_file_get. The description gives a general sense of usage (export contacts as CSV) but lacks exclusions or alternative routing, leaving the agent to infer when this is the right choice.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only operation ('Resolve' and 'Read this before a write') and gives a concrete detail about the response ('An organization API key answers `kind: api_key` with its scopes.'). However, it does not explicitly state that the tool is non-destructive or what happens when no active organization is set, but for a context-resolution 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 two sentences, front-loaded with the core purpose, and includes a critical usage warning. Every sentence earns its place: the first defines what it does, the second explains when and why to use it, and the final detail about API keys adds practical context. 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 has no parameters and no output schema, the description provides enough for an agent to understand when to call it and what kind of response to expect. It mentions the API key response type but doesn't specify the full return structure (e.g., organization ID, name). Still, for a simple context tool, this is reasonably 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 schema provides no parameter documentation. The description adds value by explaining the tool's output behavior ('An organization API key answers `kind: api_key` with its scopes.'), which helps the agent interpret the result. Since there are no params, the baseline is high, and the description contributes context beyond the empty 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's purpose: 'Resolve the active organization identity.' This is a specific verb ('resolve') and resource ('active organization identity'), and it distinguishes itself from siblings like commsharbor_me or commsharbor_organization_get by focusing on the active tenant context. It also frames its use case ('before a write when you are not certain which tenant is active'), which makes it 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?

Explicit guidance is provided: 'Read this before a write when you are not certain which tenant is active.' This tells the agent exactly when to invoke it. It also warns against guessing, which clarifies the risk of not using it. While it doesn't list alternative tools, the context is clear enough that the agent knows this is the go-to for tenant disambiguation.

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 does add useful context beyond the schema: the permission requirement (crm:write), the required 'note' field, and the return behavior (created resource with absolute URL). However, it does not disclose error behavior, validation rules, side effects, or what happens when optional fields like deal_id or activity_type are omitted, leaving some transparency 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 three short sentences with no waste. It front-loads the core action ('Creates a activity'), then quickly covers required fields, permission, and return value. It is appropriately sized for a tool of this complexity, though a minor grammatical error and lack of structure (e.g., bullets) prevent a perfect score.

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 4-parameter create tool with no annotations and no output schema, the description gives the essential facts: purpose, permission, required field, and return shape. It does not mention that organization_id is also required (only 'note' is highlighted), nor does it explain how activity_type or deal_id should be used. Given the sibling naming pattern, it could also clarify the tenant-vs-platform distinction more explicitly, so it is minimally adequate but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter meaning beyond the schema: it highlights 'note' as required. It does not clarify the expected format, allowed values, or relationships among parameters such as deal_id or activity_type, so it neither raises nor lowers the baseline. The schema's own descriptions are extremely terse but present.

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 ('Creates') and a specific resource ('a activity in the tenant CRM'). The 'tenant CRM' qualifier helps distinguish this tool from the platform_crm_activities_create sibling, though it stops short of naming that alternative explicitly. Minor grammar issue ('a activity') does not obscure meaning.

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 the tool is for creating activities within a tenant CRM, and it states a prerequisite ('Needs crm:write on the organization'). However, it does not mention when to prefer this over sibling tools like commsharbor_crm_activities_update or platform_crm_activities_create, nor does it state when not to use it. The usage context is clear but no exclusions or alternatives are given.

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 burden. It clearly indicates a destructive action and describes a key error response, but it does not mention success behavior, irreversibility, or other side effects.

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

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

The description is extremely concise with two short sentences, no fluff, and the core action is stated first. It is well-structured for quick scanning.

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 simplicity of a delete operation, the description covers the essential action, required permission, and an error case. However, it omits the success response and any details about the deletion being permanent or having cascading effects, which 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?

Both parameters have schema descriptions but they are merely repetitions of the parameter names ('activity_id', 'organization_id'), providing zero semantic insight. The description text adds no clarification about the purpose or format of these parameters 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?

Clearly states the verb 'Deletes' and the resource 'one activity' from the tenant CRM. It is specific enough to distinguish from other operations, though it does not explicitly name a sibling tool.

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

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

Provides a prerequisite (crm:write permission) and an error condition (404 for foreign/missing id), but does not indicate when to prefer this over alternative delete tools (e.g., platform vs tenant).

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

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

With no annotations, the description carries the full burden and does well: it discloses the required permission (crm:read) and the 404 behavior for foreign or missing IDs. This is meaningful behavioral context beyond the raw schema, though it does not describe response shape or pagination.

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

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

Two short sentences, front-loaded with the primary purpose, followed by permission and error behavior. Every sentence earns its place and there is 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 two-parameter get operation, the description covers purpose, scope, required permission, and a key error case. It does not explicitly describe the return value, but no output schema is provided and 'Reads one activity' reasonably implies the activity object is returned.

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 even though the schema's parameter descriptions are only the parameter names. The description adds context by tying the tool to the organization and tenant CRM, but it does not clarify formats, constraints, or how the IDs relate beyond what the schema already 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?

The description uses a specific verb ('Reads'), a clear resource ('one activity'), and a scope ('from the tenant CRM'), which distinguishes it from list/create/update/delete siblings. The singular 'one activity' makes the tool's role unambiguous even without opening the schema.

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

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

It clearly implies this is the tool for retrieving a single activity by ID, and the sibling names for listing/creating/updating/deleting provide natural contrast. It also states the required crm:read permission, but it does not explicitly say 'use list for multiple activities' or name an alternative.

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

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

No annotations are provided, so the description carries the full burden. It discloses cursor-based pagination (limit 1-100, opaque cursor), required permission (crm:read), and notes that every item includes an absolute URL. This gives a good behavioral profile, though it doesn't detail response structure or error semantics.

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 fluff. The core purpose is front-loaded, followed by pagination, filters, auth, and a response 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 covers the essential aspects: purpose, pagination, filters, auth, and a response detail. It doesn't mention sorting or default behavior beyond the schema's default limit, but for a list tool it is reasonably complete. The lack of an output schema is mitigated by the URL note.

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% but the schema descriptions are trivial (just parameter names). The description adds meaning by clarifying which parameters serve as filters (q, deal_id, contact_id, company_id, activity_type) and explains the pagination mechanics for limit and cursor. This compensates for the thin 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 explicitly states the verb ('Lists') and resource ('activities in the tenant CRM') and defines scope ('something that happened with a contact, company or deal'). It clearly distinguishes from sibling CRUD tools (create/update/delete/get) and from other list tools for different entities (companies, contacts, deals).

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 conveys when to use it: whenever a list of CRM activities is needed, with optional filters. It does not explicitly name alternatives or exclusions, but the context of sibling tools makes the usage obvious. The mention of filters and pagination gives practical guidance on how to refine the query.

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 and does well: it discloses PATCH-style semantics, the required permission, and an error condition (404). The only notable omission is the success response shape.

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

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

Three short sentences, front-loaded with the core behavior, then permission and error behavior. No filler or repetition of schema field names.

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 simple flat schema and low parameter count, the description covers the essentials for a correct call: action, partial-update semantics, required permission, and id-related error behavior. It would be more complete if it stated the success response, but the tool is simple enough that 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 the baseline is 3. The description adds meaningful parameter context beyond the schema: only sent fields change, so optional body fields act as a partial update set, and the 404 clause clarifies that activity_id must be present and belong to the organization.

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?

Begins with a specific action and resource: 'Updates one activity in the tenant CRM.' The 'one activity' qualifier plus the partial-update phrase clearly differentiates it from create/delete/get/list siblings, and 'tenant' distinguishes it from the platform-scoped update sibling.

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?

Clear context is provided: it is for modifying an existing activity, needs crm:write, and gives a 404 signal when the id is missing or foreign. It stops short of explicitly naming alternatives or when-not-to-use, so it misses 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 disclose behavior. It mentions the permission requirement (crm:write) and the return value ('Returns the created resource with its absolute url'), which are useful. However, it does not disclose side effects (e.g., potential duplicates, required field validations, or error conditions). For a mutation tool with zero annotation coverage, more detail would be expected.

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, highly concise, and front-loaded with the core purpose. Every sentence adds useful information: purpose, required field, permission, and return type. No fluff or 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?

The description explains the return format, which is good since there is no output schema. However, it leaves the optional parameters (domain, website) entirely unexplained, and does not mention any uniqueness or validation rules. For a create operation with 4 parameters, an agent would benefit from more detail on what constitutes a valid company (e.g., is name unique? does domain need to be a URL?). The description is minimal but covers the core, so it is just adequate.

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%, but the parameter descriptions are tautological (e.g., 'name', 'domain'), providing no meaning. The description only restates that name is required, which is already in the schema. It does not explain what domain or website represent or any format constraints. With such unhelpful schema descriptions, the tool description should compensate, but it does not add value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Creates a company in the tenant CRM.' It uses a specific verb (creates), resource (company), and context (tenant CRM), which differentiates it from sibling tools like commsharbor_crm_companies_delete, get, list, and update. An agent can immediately understand this is the creation 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 description implies usage for creating a company, which is clear from the context. It also states a prerequisite: 'Needs crm:write on the organization,' which is a useful guideline. However, it does not explicitly contrast with sibling create tools (e.g., contacts, deals), though the resource name makes this evident. No exclusions or alternative routing are given, so it is slightly above baseline but not fully 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?

With no annotations provided, the description carries the full burden. It discloses the permission requirement and the 404 response for missing or foreign ids, which are useful behavioral traits. However, it does not mention permanence, cascading effects on related records, or the success response 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?

The description is two concise sentences, action-first with no filler. It front-loads the purpose and then adds necessary permission and error context. 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 delete operation with two parameters and no output schema, the description covers the essential permission and error behavior. Missing details like success response and irreversible nature are minor given the simplicity and common expectations for delete operations.

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 for both parameters are tautological ('company_id', 'organization_id'), adding no semantic value. The tool description indirectly implies their meaning via 'company' and 'tenant CRM', but it does not explicitly map parameters to their roles. Schema coverage is 100%, so the baseline is 3, and the description adds only marginal context.

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 a specific verb ('Deletes'), a specific resource ('one company'), and a scope ('tenant CRM'). This distinguishes it from sibling tools like create, get, list, and update, and 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?

It provides context for use by stating the required permission (crm:write) and the behavior for invalid ids (404). While it does not explicitly contrast with alternatives, the delete intent is obvious from the name, and the permission/error details help an agent decide 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?

With no annotations, the description carries the full burden. It discloses two key behaviors: the permission requirement (crm:read) and the 404 response for foreign or missing ids. This goes beyond the schema and provides actionable knowledge for the agent. It does not describe response shape or pagination, but for a single-get operation 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?

Three sentences with zero filler. The primary purpose is front-loaded, followed by the permission requirement and the 404 behavior. Every sentence earns its place; no redundancy or off-topic 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?

For a simple get operation with only two parameters and no output schema, the description covers purpose, permission, and error handling. It does not describe the return object, but that is often implicit for a get operation. The description is sufficiently complete for an agent to call it correctly, though it could note what is returned.

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% (both parameters have descriptions, albeit trivial ones that just repeat the parameter names). The description adds no extra meaning about organization_id or company_id, leaving the agent to infer from the names. Baseline of 3 is appropriate since the schema already documents both parameters; the description does not compensate 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?

States a specific verb ('Reads'), resource ('one company'), and scope ('tenant CRM'). The phrase 'one company' distinguishes it from list operations, and the mention of id-based lookup is implied by 'a foreign or missing id answers 404.' Clearly distinguishable from siblings like commsharbor_crm_companies_list and commsharbor_crm_companies_update.

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 the use case (fetching a single company by id) but does not explicitly name alternatives or provide when-not-to-use guidance. It mentions the permission requirement (crm:read) but that is a prerequisite rather than usage context. No exclusions or comparisons to list/create/update tools are given, leaving some inference to the agent.

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

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

With no annotations, the description carries the full burden and does meaningfully disclose behavior: the endpoint is cursor-paginated, requires crm:read on the organization, and returns items with an absolute URL. It stops short of describing error or rate-limit behavior, but for a read-only list tool this is strong disclosure.

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 short, front-loaded with the primary action, and packs pagination, filtering, authentication, and output URL information into a compact form. The middle em-dash clause is slightly confusing and does not earn its place as cleanly as the rest, preventing a 5.

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

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

For a list endpoint with no output schema, the description covers the key operational details: required organization context, pagination cursor/length, filtering via q, permission requirement, and a guarantee that every item has an absolute URL. It does not describe the full item shape or error cases, but an agent has enough to invoke it correctly.

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

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

Although schema coverage is 100%, the schema's descriptions for q and organization_id are tautological ('q', 'organization_id'). The description compensates by clarifying the cursor mechanism, the limit range, the q filter, and the permission context tied to the organization, adding meaning beyond the schema.

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

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

The description opens with a specific verb, 'Lists', and a clear resource, 'companies in the tenant CRM', so an agent can immediately identify the operation. It does not explicitly name a sibling alternative for comparison, and the em-dash clause defining companies is somewhat awkward, so it falls short of a 5.

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

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

The description provides practical context: pagination parameters (limit 1-100, opaque cursor), a q filter, and a crm:read permission requirement. However, it does not state when to choose this over sibling tools (e.g., getting a single company) or mention exclusions, so 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?

With no annotations provided, the description carries the full burden. It discloses the partial-update behavior, the required permission, and the 404 response for invalid or missing ids. This is significant behavioral context beyond the schema. It does not mention the return format, but for a mutation this is often not critical.

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 with no fluff. It front-loads the primary purpose, then adds permission and error behavior. Every sentence earns its place, and the structure is efficient and clear.

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 covers the essential aspects: action, partial update, permission, and error handling. It does not describe the response body, but that is not always required for mutations. The description is sufficiently complete for an agent to call the tool correctly, though it could explicitly note that only required fields are identifiers.

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%, but each parameter's description is just the field name (e.g., 'name', 'domain'). The description adds real semantics by clarifying that only provided fields change, implying the optionality of non-required fields. It also indicates that company_id and organization_id are identifiers via the 404 behavior. This adds meaning beyond the minimal schema descriptions.

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

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

The description clearly states the action (update), the target (one company in the tenant CRM), and the key behavior (only the fields sent change). This differentiates it from create/delete/get/list and other entity updates. The verb and resource are specific 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 (update an existing company) but does not explicitly state when to use it versus alternatives like create, delete, or get. It provides a permission requirement (crm:write) and an error condition (404 on bad id), which are contextual but not explicit routing to sibling tools. A clear 'use this when modifying an existing company' would have been stronger.

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

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

With no annotations, the description carries the full burden and does it well: it discloses that this is a mutating operation, the required permission, the return shape ('created resource with its absolute url'), and a meaningful behavioral caveat about consent living in the marketing sub-resource. This goes well beyond the simple verb.

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

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

Three tightly packed sentences, each earning its place: what it does, what is required/permitted, what is returned, and an important non-obvious caveat. No filler or repetition of schema 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?

The description is complete for a simple create tool: it states required fields, permission, return value, and a crucial compliance boundary. It does not explicitly mention organization_id in the required list, though the schema marks it required, which 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 description coverage is 100%, so the baseline applies because the schema already documents every parameter. The description adds some context about required fields and the marketing/consent sub-resource, but it does not add meaningful meaning to individual parameters like company_id or organization_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?

States a specific verb and resource: 'Creates a contact in the tenant CRM.' It clearly distinguishes itself from sibling contact operations (get/list/update/delete) and names the minimally required fields. The scope is immediately understandable.

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 being a create operation and mentions the required crm:write permission, but it does not explicitly state when to use this tool versus update/list or when not to use it. There are no exclusions or alternatives 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 and covers key behavioral aspects: it discloses the required permission ('crm:write'), the error behavior for missing or foreign IDs ('answers 404'), and a domain-specific nuance about consent residing in the 'marketing' sub-resource. This goes beyond the schema and adds meaningful context, though it doesn't detail side effects or idempotency.

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 well-structured: it opens with the core purpose, then delivers critical operational details (permission, error behavior, consent caveat) in just four sentences. No filler or redundancy, and it front-loads the most important 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 delete operation with two parameters and no output schema, the description covers the essential operational context: purpose, permission, error handling, and a relevant domain rule. It doesn't address potential side effects or reversibility, but given the simplicity, it is reasonably 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 schema provides descriptions for both parameters, but they are just the parameter names ('contact_id', 'organization_id') with no added semantics. The description does not elaborate on these parameters either. Since schema coverage is 100% but trivial, the description adds no extra value, so a 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 clearly states the action ('Deletes one contact') and the resource ('tenant CRM'), distinguishing it from sibling operations like get, create, or update. The verb and object are explicit, 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 implies usage by naming the delete operation, but it does not explicitly compare with alternatives or state when to prefer this tool over others. It also doesn't mention when not to use it. However, the intent is clear enough that an agent can infer it's for removing contacts.

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 permission requirement ('Needs crm:read on the organization'), error behavior ('A foreign or missing id answers 404'), and a non-obvious consent caveat ('Being in the CRM is not permission to email: consent lives in the marketing sub-resource'). It does not describe the return format, but for a simple read that is a minor 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 three sentences with no waste. The primary purpose is front-loaded, followed by essential operational details (permission, error handling, consent). Every sentence adds value and there is no redundant phrasing.

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 covers the critical aspects: operation type, required permission, error response for missing/foreign IDs, and a consent nuance. It does not describe the response structure, but for a single-contact read that is often inferred. The coverage is sufficient for an agent 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 100%, but the descriptions are tautological (just the parameter names). The tool description adds no additional meaning to contact_id or organization_id, though it implies contact_id identifies the contact and organization_id identifies the tenant via context. This meets the baseline of 3 but does not exceed 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 states a clear verb ('Reads') and resource ('one contact from the tenant CRM'), immediately distinguishing it from list, create, delete, and update siblings. It also specifies the scope ('tenant CRM') and implies a single record retrieval by ID, which 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 does not explicitly name alternatives or state when to use this tool versus commsharbor_crm_contacts_list or others. It provides context about required permission (crm:read) and a consent caveat, but the selection guidance is only implied by the verb 'Reads one contact' rather than explicit exclusions or references to 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 provided, the description carries the full behavioral burden and does so exceptionally: it discloses cursor pagination mechanics, limit range, opaque cursor reuse, permission requirements, absolute URL per item, and an important compliance caveat about CRM membership not granting email permission. This is far beyond a generic list 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 compact and well-ordered: definition, pagination, filters, permission, output guarantee, then the consent caveat. Every sentence adds distinct value without redundancy, and critical details are front-loaded.

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

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

For a list endpoint with 5 params and no output schema, the description covers invocation essentials: required permission, pagination, filter parameters, and a subtle behavioral caveat about email consent. Nothing critical for an agent to select and call the tool 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?

Although schema coverage is 100%, the schema descriptions are mostly tautological ('q', 'company_id', 'organization_id'). The description adds real meaning by identifying q and company_id as filters, constraining limit to 1-100, and explaining cursor as opaque and derived from the previous page, which compensates for the weak 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 description opens with a specific verb and resource: 'Lists contacts in the tenant CRM', and clarifies what a contact is ('a person in the tenant CRM'). It distinguishes this list operation from the sibling get/create/update/delete contact tools through its explicit listing focus and pagination cues.

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 for when to use the tool: listing with cursor pagination, filters (q, company_id), and the required crm:read permission. It does not explicitly contrast with alternatives like commsharbor_crm_contacts_get or commsharbor_contacts_export, but the listing semantics and filter hints make the intended use unambiguous.

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

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

No annotations are provided, so the description must disclose behavior. It does: mutation, required permission (crm:write), 404 on invalid id, and the domain-specific caveat that CRM membership does not grant email consent. This covers authorization, error, and domain constraints well, though it omits details like idempotency or response format, which are minor for a simple update.

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, each with a distinct purpose: core action, permission requirement, and error/consent caveat. It is front-loaded with the primary purpose and avoids fluff. Every sentence earns its place, making it efficient and 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?

For a simple mutation tool with fully described parameters and no output schema, the description covers the essential operational aspects: permission, error handling, and a critical domain rule. It could mention the response format, but that is not necessary for correct invocation. Overall, it is sufficiently complete for an agent to use it correctly.

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

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

The input schema describes all 5 parameters with simple labels (email, company_id, contact_id, etc.), achieving 100% coverage. The description adds meaningful context by stating that only sent fields change (partial update) and that contact_id must be valid. However, it does not elaborate on each parameter beyond the schema, so it stays at the baseline 3 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 states the action precisely: 'Updates one contact in the tenant CRM' with a specific resource (contact) and verb (update). It distinguishes from sibling tools by emphasizing partial update semantics ('only the fields you send change') and by contrasting with create/delete/get/list siblings. This 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 gives clear usage context: it requires crm:write permission, explains error behavior for missing/foreign ids (404), and warns that email consent is handled separately in the marketing sub-resource. It doesn't explicitly name alternative sibling tools (e.g., 'use create for new contacts'), but the guidance is sufficient for an agent to decide when to use this 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 present, the description carries the full disclosure burden and does substantial work: it states the required permission (crm:write), declares the return behavior (created resource with absolute url), and documents the minor-units convention with a concrete conversion example. This last point is genuinely subtle behavioral context that would otherwise cause real-world bugs. It does not cover idempotency or conflict behavior, but the critical mutation-relevant traits are 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 zero filler, each one earning its place: the core action and requirements, the permission and return contract, and a subtle unit convention with a concrete example. The minor-units example is slightly verbose but is exactly the kind of clarification that prevents a costly bug. Front-loading is correct — the action and requirements come first.

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

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

For a create tool with no output schema and no annotations, the description covers the essential contract: required inputs, the permission needed, and what is returned. The money-unit clarification is especially valuable given the flat schema. Minor gaps remain — the response shape beyond the URL isn't sketched, and there's no mention of behavior on duplicate/conflicting values — but nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema description coverage is reported at 100%, but every schema description is a tautological one-word echo of the parameter name ('title', 'currency', 'value_minor'), so the schema carries essentially no semantic weight. The description compensates for the money fields by explaining the value_minor/currency pairing and unit scale, but adds nothing for title, pipeline_id, stage_id, or organization_id beyond what the schema itself implies. Baseline 3 is appropriate: the description only partially compensates for the weak schema semantics.

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

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

The description states a specific verb and resource: 'Creates a deal in the tenant CRM.' The 'tenant CRM' qualifier usefully distinguishes it from the commsharbor_platform_crm_* sibling family, and the create verb sets it apart from the other commsharbor_crm_deals_* operations (get/list/update/delete). It lacks an explicit contrast with those siblings, but the intent 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 implies its usage context (creating a deal) and adds scope context ('tenant CRM' vs the platform-level siblings), but it never explicitly states when to choose this tool over alternatives, nor does it list exclusions such as using update for existing deals. Requirements are implied through 'Required: title, pipeline_id, stage_id' but are stated in prose rather than as explicit when-to-use guidance.

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

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

With no annotations, the description carries the behavioral burden and addresses key runtime behavior: the needed auth scope, the 404 response for foreign or missing ids, and the destructive intent. It doesn't mention irreversibility or side effects, but for a simple delete operation that would be expected.

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

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

Three short sentences, front-loaded with the primary action and scope. The auth requirement and 404 behavior each earn their place; the minor-units note is somewhat tangential to deletion but does not bloat the description.

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 delete with no output schema, the description covers the core invocation concerns: scope, permission, and error behavior. It does not describe the success response, but that is less critical when no output schema exists and the operation is straightforward.

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

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

Schema coverage is 100%, so both parameters are at least named in the schema, but their descriptions are tautological ('deal_id', 'organization_id'). The tool description adds context about tenant/org scope and auth, but no concrete parameter-level meaning 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 states a specific verb and resource ('Deletes one deal from the tenant CRM') and clarifies the singular scope ('one deal'). It clearly separates this from sibling deal tools like create, get, list, and update.

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 conveys when to use it: to delete a single deal, and it supplies the required permission ('crm:write on the organization'). It does not explicitly name alternatives or exclusion cases, but the context is clear enough for an agent to select it correctly.

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 behavioral burden and does so well. It discloses the required permission, the 404 behavior for foreign/missing IDs, and the important money-unit convention in responses. These are non-obvious traits an agent needs to interpret results correctly.

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, each earning its place: what the tool does, the permission needed, and the two behavioral caveats (404 and currency units). No filler or 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 simple single-get operation with two required parameters and no output schema, the description covers the essential operational details: permission, error semantics, and response value interpretation. Nothing critical is missing for an agent 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 100%, but the schema descriptions are only the parameter names themselves. The description adds context by tying organization_id to the tenant and crm:read permission, and deal_id is implied by 'one deal.' However, it does not explain ID formats or where to obtain them, so it remains at the baseline for schema-covered 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 and resource: 'Reads one deal from the tenant CRM.' It clearly distinguishes this from list operations such as commsharbor_crm_deals_list by emphasizing a single deal, and the resource is unambiguous.

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

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

The description gives concrete usage context: it requires crm:read permission and states that foreign or missing IDs return 404. It does not explicitly contrast with sibling list/get tools, but the 'one deal' wording and error behavior make the intended use 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 of behavioral disclosure. It reveals cursor-based pagination with a limit range, opaque cursor semantics, required permission scope, and a critical data-format caveat (minor units with a concrete example). These are non-obvious behaviors that prevent misinterpretation and go well beyond a generic list 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 three sentences with no filler. It front-loads the purpose, then packs pagination, filters, auth, and a concrete money-unit example into the remaining text. Every clause earns its place and no information is needlessly repeated.

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

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

The description covers the main operational essentials: purpose, pagination, filters, auth, and a hint about response items (absolute url and money units). However, it does not enumerate the full deal fields returned, ordering guarantees, or error/empty behavior, and there is no output schema to compensate. This is a minor gap given the tool's 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?

Although all parameters have schema descriptions, they are merely echoed names (e.g., 'q', 'status'). The description adds real meaning: limit bounds and cursor reuse, identifies which parameters act as filters, and connects organization_id to the tenant and permission context. This lifts it above the baseline 3 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 states a specific verb and resource: 'Lists deals in the tenant CRM — an opportunity moving through a pipeline.' It clearly distinguishes this from sibling tools like crm_deals_get, crm_deals_create, and other CRM list endpoints by naming the exact resource (deals) and its domain context (pipeline opportunities).

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 context for when to use the tool: it lists deals with filters and pagination, and requires crm:read permission. It does not name alternative tools or explicit when-not-to-use conditions, but the role as a list/filter/paginate operation is clearly conveyed.

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

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

With no annotations, the description carries the full burden and does so well. It discloses the partial-update semantics, the required permission (crm:write), the 404 error on missing/foreign IDs, and the minor-unit money format. It does not specify the response on success (e.g., whether the updated deal is returned), which is a minor gap for a mutation tool, but the provided behavioral details are substantial.

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 core purpose and partial-update behavior, followed by permission, error, and unit clarifications. Every sentence provides necessary information with no waste or redundancy.

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

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

Given no output schema and no annotations, the description covers essential operational details: partial update, permission, error behavior, and unit semantics. It lacks a statement about what the tool returns on success, which would be helpful for an agent to know if it needs to fetch the result, but overall it is quite complete for a focused update 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?

The input schema has high coverage (100%) but the descriptions are trivial (just parameter names). The description adds meaningful context for value_minor and currency by explaining the minor-unit relationship, which is critical to avoid misuse. Other parameters like title, stage_id, and pipeline_id are self-explanatory, so the description compensates adequately for the schema's lack of detail.

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 ('Updates'), a clear resource ('one deal'), and a distinctive scope ('in the tenant CRM'). It also clarifies the partial-update behavior ('only the fields you send change'), which distinguishes it from other deal operations like create, delete, or get. The name and description together unambiguously identify the tool's purpose.

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 implies usage when an agent needs to update a single existing deal, but it does not explicitly contrast this tool with alternatives such as commsharbor_crm_deals_create or commsharbor_crm_deals_get. No 'when-not' or alternative-routing guidance is provided, so usage is inferred rather than stated.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses the permission requirement (crm:write) and the return value (created resource with absolute URL), which are useful. However, it does not mention side effects beyond creation, potential failure modes, or any constraints on stages. 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 a single sentence that front-loads the core action ('Creates a pipeline'), then packs required fields, permission, and return value with zero waste. It is efficient and well-structured.

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

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

For a simple create operation with three parameters and no output schema, the description covers the main purpose, a required field, permission, and return type. However, it omits that organization_id is also required and does not describe the optional stages parameter. These gaps are partially filled by the schema but could be clearer in text.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that 'name' is required, but it does not mention 'organization_id' as required (though the schema does). It also does not explain the 'stages' parameter beyond what the schema provides. The description adds minimal value over 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 states a specific verb and resource: 'Creates a pipeline in the tenant CRM.' This clearly distinguishes it from sibling operations like list, get, update, and delete. It also mentions required field and permission, further clarifying the action.

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

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

The description implies usage (when you need to create a pipeline) but does not explicitly compare to alternatives or state when not to use it. The mention of the required crm:write permission is a form of guidance, but there is no explicit routing away from other pipeline 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?

The description discloses the destructive action and error behavior, but without annotations it carries the full burden. It does not mention whether deletion is permanent, cascades to related stages or deals, or returns any confirmation payload.

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 compact sentences with no redundant wording. Each clause adds useful information: the action, the permission requirement, and the 404 behavior.

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 delete operation with no output schema, the description covers the essential action, required permission, and error case. It omits only optional details like success response shape or cascading effects, which are not strictly necessary 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 descriptions are only the parameter names, so the baseline is neutral. The tool description adds context like 'tenant CRM' and 'foreign or missing id' but does not explicitly define organization_id as the tenant identifier or clarify pipeline_id semantics beyond the self-explanatory name.

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 ('Deletes'), the resource ('one pipeline'), and the scope ('from the tenant CRM'). It unambiguously distinguishes this tool from the sibling create, get, list, and update pipeline 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 intended use is evident from the verb and resource, and the description adds the prerequisite 'crm:write on the organization' plus 404 behavior for foreign or missing IDs. It does not explicitly contrast with alternatives, but no plausible alternative exists for deleting a pipeline.

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?

It discloses the required permission (crm:read) and error semantics (404 for foreign or missing id), which is valuable context beyond the schema. Since no annotations are provided, the description carries the full burden and does it well, though it doesn't detail the return payload.

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 wasted words. The core purpose is front-loaded, and the permission and error details follow logically 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 read operation, it covers permission and error cases, which is sufficient for calling the tool correctly. However, it doesn't mention the return format, and with no output schema, a note like 'Returns the pipeline object' would improve completeness. Still, it's largely adequate.

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 descriptions are merely the parameter names, adding no real meaning. The description adds no extra parameter details either, but schema coverage is 100%, 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?

The description states a specific verb ('Reads') and resource ('one pipeline') and clarifies it's from the tenant CRM. This clearly distinguishes it from list operations like commsharbor_crm_pipelines_list and other entity gets, making the 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 implies singular use by saying 'one pipeline' but doesn't explicitly name alternatives or when to use the list sibling. It could benefit from stating 'For multiple pipelines, use commsharbor_crm_pipelines_list,' but the singular phrasing provides some 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 full burden of behavioral disclosure. It explicitly states the tool is cursor-paginated, with limit range and opaque cursor mechanics, and that every item includes an absolute URL. It also discloses the auth requirement (crm:read). This goes beyond basic schema info and gives the agent a clear picture of how the tool behaves. It does not contradict any annotations (none provided).

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 compact three sentences, front-loaded with the core purpose, followed by pagination details, filters, permission, and a response hint. Every sentence adds distinct information with no redundancy or filler. It is well-structured and 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 list tool with no output schema, the description covers essential aspects: pagination mechanics, filter, required permission, and a hint about response items (absolute URL). It does not describe the full structure of a pipeline object, but that is not required given the tool's simplicity. The description is sufficiently complete for an agent to call it correctly and understand the result format at a high level.

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 value by explaining the q parameter as a filter, the limit as page size (1-100), and cursor as an opaque value from the previous page. This is more informative than the schema's bare 'q' and 'cursor' descriptions. It doesn't add much on organization_id, but that is a standard identifier. Overall, it enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool lists pipelines in the tenant CRM, and defines a pipeline as a named sequence of stages. This distinguishes it from other CRM list tools like deals, contacts, or stages. The verb 'lists' and specific resource 'pipelines' make the 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 provides clear context on when to use the tool by naming the resource (pipelines) and giving operational details like cursor pagination and filters. It does not explicitly mention alternatives or exclusions, but the resource-specific naming makes the intended use obvious. It also mentions the required permission (crm:read), which helps the agent decide if this is the right call.

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 partial update semantics ('only the fields you send change'), the required permission (crm:write), and error behavior (404 for foreign/missing id). This is strong for a mutation tool, though it does not mention the return value or whether it is idempotent.

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, no filler, and the core purpose is front-loaded. 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?

The description covers the key aspects an agent needs: what the tool does, permission requirements, error handling, and partial update semantics. For a simple update with two required IDs and two optional fields, this is sufficient. It does not mention return format, but no output schema is present, and the description does not promise one.

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 clarifying that only sent fields are updated, which gives meaning to the optional name and stages parameters. It does not elaborate on stages format beyond what the schema already states, so it does not exceed the 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 verb ('Updates') and the resource ('one pipeline in the tenant CRM'), and specifies partial update behavior. It distinguishes itself from sibling create/delete/get/list tools by focusing on updating an existing pipeline.

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 (updating an existing pipeline) and states a prerequisite (crm:write permission). It does not explicitly name alternatives like the create tool, but the context is clear enough for an agent to decide.

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 required permission (crm:write) and the return format (created resource with absolute url), which are useful behavioral details beyond the schema. It does not cover idempotency or error cases, but the provided info is substantive.

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 and required field are front-loaded, followed by permission and return info. Every word adds value.

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

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

The description omits that organization_id and pipeline_id are also required, which could mislead an agent into thinking only name is needed. It gives return and permission info, but for a tool with 5 parameters and no output schema, this is a noticeable gap. It also does not explain the meaning of optional fields, though those are 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%, but the schema descriptions are trivial (just property names), so the baseline is 3. The description adds only 'Required: name', which is already in the schema, and does not clarify the semantics of position, probability, or the role of organization_id and pipeline_id. It provides no meaningful compensation for the weak schema.

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

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

The description clearly states the verb ('Creates') and the resource ('a stage in the tenant CRM'), which distinguishes it from sibling tools like delete, get, list, and update. It also mentions a required field, reinforcing the specific action.

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

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

The description implies usage for creating new stages but does not explicitly compare with alternatives or state when not to use it. It provides constraints like the required name and crm:write permission, but these are more about invocation conditions than choosing among 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 provided, the description carries the full burden of behavioral disclosure. It does disclose the required permission ('Needs crm:write on the organization') and the error behavior for missing or foreign IDs ('A foreign or missing id answers 404'). However, it omits what happens on success (e.g., return payload or status) and whether deletion is irreversible or cascades to associated records. It gives some key behavior but not a complete picture.

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

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

The description is two sentences long and front-loaded with the primary action. It states what the tool does first, then adds the essential permission and error context. There is no fluff or repetition. Every sentence earns its place, making it highly efficient for an agent 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?

For a delete operation with three required parameters and no output schema, the description covers the action, the permission prerequisite, and a notable error condition (404). It does not describe the success response or any cascading effects, but for a straightforward deletion, these are secondary. The core information an agent needs to decide and execute correctly is present. Minor gaps are acceptable 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 input schema covers all three parameters, but each description is just the parameter name (e.g., 'stage_id'), providing no semantic detail. The tool description itself does not elaborate on the parameters. However, the parameter names are self-explanatory: stage_id, pipeline_id, organization_id. Since schema coverage is 100% and the names are meaningful, the description does not need to compensate, but it also adds no extra value beyond the schema. 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 clearly states the action: 'Deletes one stage from the tenant CRM.' It specifies the resource (stage), the scope (tenant CRM), and the operation (delete). This distinguishes it from sibling tools like create, get, list, and update stages. The wording is direct 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 provide any guidance on when to use this tool versus alternatives. It does not mention scenarios where deletion is appropriate or contraindicated, nor does it reference sibling tools. The only usage hint is the permission requirement, which is more about prerequisites than selection criteria. An agent gets no explicit direction on when to pick this delete over other stage 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?

With no annotations, the description carries the behavioral burden. It discloses the read-only nature, the permission requirement, and the 404 behavior for foreign or missing ids, which is meaningful beyond the tool name and schema.

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

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

Three short sentences, each carrying distinct information: operation, auth requirement, and error behavior. No filler or 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 simple three-string-parameter read, the description provides purpose, permission, and error semantics; nothing needed to call it correctly is absent. Return-shape detail is not essential for this get tool.

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

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

Schema coverage is 100%, so the baseline is met; the schema's descriptions are tautological but the parameter names are self-explanatory. The description adds minimal parameter-level meaning beyond the id-relationship implied by 'foreign 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 opens with 'Reads one stage from the tenant CRM', giving a specific verb, resource, and singular scope. This clearly distinguishes it from list, create, update, and delete stage 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?

It clearly implies use for retrieving a single CRM stage and adds a prerequisite ('Needs crm:read on the organization'). It does not name sibling alternatives or specify when not to use it, so it falls just short of explicit routing 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 fully carries the transparency burden. It discloses cursor pagination, page-size bounds (1-100), the required auth scope (crm:read), and a response property (absolute url). It does not mention ordering, rate limits, or the exact next-cursor field, but for a read-only list this is a solid disclosure.

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 purpose is front-loaded, followed by pagination, auth, and return-value detail. 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 provides the required scope, pagination mechanics, permission, and item-level detail, which is enough to invoke the tool correctly. Since there is no output schema, it could have added next-cursor or ordering details, but nothing essential to a successful 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%, so the schema already documents limit, cursor, pipeline_id, and organization_id. The description reinforces that pipeline_id is the scoping parameter and repeats pagination details, but it adds little meaning beyond the schema.

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

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

The description uses a specific verb and resource: 'Lists stages in the tenant CRM' and clarifies that stages are scoped to a pipeline. This distinguishes it from stage get/create/update/delete tools and from pipeline list tools. 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?

It clearly conveys the structural context: stages belong to a pipeline and are listed under that pipeline, so an agent knows to supply pipeline_id. It also states the crm:read permission requirement. However, it does not explicitly name alternative tools or exclusion conditions, 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 provided, so description carries the burden. It discloses partial-update behavior, permission requirement, and 404 for invalid IDs. This is good but could mention success response or idempotency; still above average 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?

Three concise sentences with the action first, then partial-update nuance, then permission and error. No filler, information-dense and 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 6-param tool with no output schema and no annotations, it covers the essential behavioral aspects: what it does, partial update, permission, and error handling. It doesn't explain parameter meanings (e.g., probability range) but schema covers their names, so it's reasonably 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 covers all 6 parameters with descriptions (though those are just names). The description adds no parameter-specific meaning beyond what schema provides, so baseline 3 is appropriate.

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

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

Clearly states it updates one stage in the tenant CRM, distinguishing it from create/delete/get/list siblings. The phrase 'only the fields you send change' clarifies it is a partial update, adding specificity.

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

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

Implicitly indicates usage (updating an existing stage) and provides prerequisites (crm:write permission) and error behavior (404 for foreign/missing id). However, it does not explicitly compare to alternatives like the create or delete tools, but the context is clear enough.

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

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

With no annotations present, the description carries the full behavioral disclosure burden. It transparently states this is a create operation, the authorization requirement (crm:write on the organization), and the return shape (the created resource with its absolute URL). It does not describe potential side effects or idempotency, but for a simple creation 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 short sentences deliver purpose, key requirement, permission, and return value with no filler. The most important information is front-loaded, and every sentence earns its place.

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

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

For a 4-parameter create tool, the description covers the core facts needed to invoke it correctly: what it does, required fields (mostly), authorization, and the response. There is no output schema, so the explicit return-value note is valuable. The main gap is that it does not explain what organization_id represents in relation to the tenant CRM or how deal_id connects to an existing deal, but these are obtainable from the schema and domain context.

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

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

Schema description coverage is 100%, so the baseline is 3, but the schema descriptions are mostly tautological ('title', 'status', 'deal id'). The description adds some meaning by flagging title as required and tying the operation to an organization, but it does not clarify the relationship of deal_id to the task or explain the status semantics beyond the enum. It also highlights title as required while omitting that organization_id is also required per 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-resource pair ('Creates a task') and scopes it to the tenant CRM, which clearly distinguishes it from getting, updating, deleting, or listing tasks. This is enough to separate it from the many sibling CRM tools without needing to inspect schemas.

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

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

The description gives useful operational context by noting the required title and the crm:write permission needed on the organization. However, it does not explicitly guide the agent on when to choose this tool over related alternatives, such as commsharbor_platform_crm_tasks_create or the other CRM create tools, so usage guidance is mostly 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.