commsharbor

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful non-structured context: audit records are immutable and never contain recipient PII, which materially affects how an agent may use and report the results.

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

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

Two short sentences, zero filler, with the resource scope front-loaded and the two behavioral guarantees following. Every clause earns its place.

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

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

For a simple read-only list tool with annotations covering safety, the description is nearly sufficient; the immutability/PII notes are a real bonus. The only gap is that cursor-based pagination behavior is not described, though the schema names the cursor parameter.

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

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

Schema coverage is 100% with only two parameters, so the schema fully documents organization_id and the opaque cursor. The description adds no syntax or semantics beyond the schema, which is the expected 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?

States a specific verb ('List') and resource ('tenant audit events'), so the agent knows exactly what the tool returns. It doesn't differentiate from siblings, but no sibling overlaps the audit domain, so ambiguity is low.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. required permissions or org context), and no named alternatives. The agent must infer that this is a read-only listing call from the name alone.

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

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

Annotations already declare a safe read-only, idempotent operation, but the description adds substantial context beyond those hints: it explains the sample sources, total-only privacy, the share formula, how DMARC and SPF are treated, and the largest-remainder rounding rule. This is rich behavioral disclosure for a no-parameter report.

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

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

The description is dense but front-loaded with the report's purpose, then follows with necessary caveats about scope and computation. Every sentence provides relevant context, though some calculation details are borderline for a no-parameter read 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?

With no output schema, the description must carry the burden of explaining return values and methodology. It does so thoroughly: totals only, no domains listed, share formula, DMARC vs SPF handling, and rounding. Nothing essential for correct interpretation 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?

There are zero input parameters, so the description has no parameter semantics to clarify. The baseline for a 0-parameter tool is 4, and the schema correctly reflects that no input is required.

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: read the monthly Brazil email security report, covering DMARC rejection and SPF endings for government, banks, and listed companies. It clearly distinguishes this public report from the sibling domain/account management tools by naming the exact dataset and 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 explains when the report applies (monthly, public DNS, free, no account) and implies use for aggregate research rather than domain-specific checks. It does not explicitly name alternative tools such as commsharbor_email_security_check, but the context and constraints are clear.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description still adds value: it explains the risk of guessing (data landing in the wrong organization) and partially discloses the return shape ('kind: api_key' with scopes). It does not detail full response fields, but adds real context beyond annotations.

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

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

Front-loaded with the core action, followed by the trigger and the return hint. 'Guessing is how data lands in the wrong organization' is slightly rhetorical but earns its place as a motivating risk statement. Reasonably tight overall.

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

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

No output schema exists, yet the description covers the return hint (org API key -> kind: api_key with scopes), the invocation condition, and the consequence of misuse. For a zero-parameter, read-only context resolver this is complete enough to call 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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly does not invent any.

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

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

It states a specific verb and resource: 'Resolve the active organization identity.' Clear what the tool does. However, it does not distinguish itself from nearby siblings like commsharbor_me, commsharbor_organization_get, or commsharbor_platform_context, so an agent has to infer which identity/context tool to pick.

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?

'Read this before a write when you are not certain which tenant is active' gives an explicit invocation condition, and the wrong-tenant warning reinforces the trigger. It stops short of naming alternatives or stating when NOT to call it.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real behavioral context beyond them: no guest access, the permission model, server-side credential handling, and that mailbox passwords and message content are never returned. No disclosure of what happens if a destination mailbox does not exist, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the create action and scope, then constraints. Nothing is padded, though the permissions/security sentences read as a list of statements rather than a tightly integrated explanation.

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

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

For a 5-required-parameter mutation with no output schema, the description covers authorization and confidentiality well, but never says what a successful call returns (e.g., an alias identifier) nor how failures are surfaced, leaving an agent to guess at the result shape.

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 five required parameters are already documented. The description adds no parameter-level detail beyond the schema (no naming rules for local_part, no idempotency_key semantics), so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an alias to existing mailboxes in this organization'), which cleanly separates it from sibling lifecycle tools like commsharbor_email_alias_update, _suspend and _resume. It does not name a sibling explicitly, so it falls just short of 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?

Gives usable context: destinations must be existing mailboxes in the organization, guest access is excluded, and the permission tiers (members read; owners/admins/org keys manage) tell an agent whether the caller is eligible. However, it never states when to prefer this over alias_update or what preconditions (e.g., verified domain) must hold, so 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?

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is partly covered, but the description adds real value: the restore does not alter destinations, guests are excluded, the private service credential stays server-side, and mailbox passwords/message content are never returned. It omits idempotency semantics despite the required idempotency_key and does not say what happens if the alias is not currently suspended.

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?

Five short sentences, front-loaded with the core action and effect before the permission and data-handling clauses. Efficient overall, though the credential/password clauses read as boilerplate that recurs across the Commsharbor family rather than information unique to this call.

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

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

No output schema exists, and the description partially compensates by stating what is never returned (passwords, message content). Permissions and non-mutation of destinations are covered. What is missing is the response shape for a successful resume and behavior on an already-active or nonexistent alias.

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 three documented parameters (resource_id, idempotency_key, organization_id), so the schema already carries the parameter burden. The description adds no per-parameter syntax, format, or sourcing guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Restore a suspended alias') plus a scope constraint ('without changing its destinations') that separates it from sibling operations like commsharbor_email_alias_update and commsharbor_email_alias_suspend. An agent can distinguish this from its siblings without opening any 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?

Provides a clear permission context: 'No guest access. Members can read. Owners, admins and organization keys can manage email.' This tells the agent who can invoke the tool. It does not, however, explicitly state when to prefer this over alias_update or how it relates to alias_suspend, so it stops short of full 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?

Annotations already declare destructiveHint=false and readOnlyHint=false, and the description's "without deleting its configuration" is consistent with that non-destructive profile. It adds real behavioral context the annotations do not: permission requirements (owners/admins/org keys), "No guest access", and that the private service credential stays server-side.

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 critical operation is front-loaded in the first sentence, which is good. But the trailing boilerplate about service credentials and "mailbox passwords and message content are never returned" is generic for a suspend operation and doesn't clearly earn 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?

Covers permissions, non-destructiveness, and credential handling, which is solid for a mutation tool with no output schema. It is silent on operational consequences an agent might need (does the mailbox keep receiving mail, is suspension reversible, what the response signals), leaving clear gaps.

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

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

Schema description coverage is 100%, with all three required params (organization_id, resource_id, idempotency_key) documented in the schema itself. The description adds no format, example, or meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Suspend an alias") and adds a scope constraint ("without deleting its configuration"). It is clearly distinguishable from the sibling resume/create/update tools by the verb, though it never names the resume sibling as its counterpart.

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 verb and the "without deleting" caveat, and the permission sentence ("Owners, admins and organization keys can manage email") hints at who may invoke it. However, there is no explicit when-to-use versus commsharbor_email_alias_resume or update, and no stated prerequisites.

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

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

Annotations only supply the safety flags (readOnlyHint=false, idempotentHint=false, destructiveHint=true); the description goes further by disclosing the authorization model and confidentiality guarantees (service credential stays server-side, mailbox passwords and message content never returned). It does not state that existing destinations are replaced or that the change is irreversible, which is the main remaining gap given destructiveHint=true.

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?

Five short sentences, front-loaded with the core action, with no wasted wording. The trailing credential/password sentences read as a reusable boilerplate block but still add relevant confidentiality context.

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

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

For a destructive, 4-required-parameter mutation with no output schema, the description covers permissions and data handling but omits what happens to the prior destinations, whether the operation is reversible, and how the idempotency_key affects retries. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, and the description adds no format or semantic detail about destinations, resource_id, or idempotency_key. Baseline 3 is appropriate when the schema carries the full parameter burden.

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: 'Change the alias destinations within this organization.' An agent can distinguish this mutation from siblings like commsharbor_email_alias_create or commsharbor_email_alias_suspend. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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 commsharbor_email_alias_create or the mailbox update tools, nor any stated prerequisites beyond authorization roles. The role sentence ('No guest access. Members can read. Owners, admins and organization keys can manage email.') is access control, not usage 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?

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds genuine value beyond that: it is a durable request that waits for operator activation, does not change DNS, does not expose provider credentials, and that mailbox passwords and message content are never returned. It does not detail what the operator does on activation or expected latency, but the disclosure is substantially richer than the annotations.

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

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

The description is a series of short declarative sentences. Some earn their place (durable/actor model), but others read as unconnected security boasts ('No guest access. Members can read.') that are not clearly tied to this specific tool invocation.

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

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

For a 3-parameter mutation with no output schema, the description covers the actor model and side-effect profile but omits the return value shape or what an agent should do after requesting assistance. It is adequate but leaves operational gaps for a request-style tool.

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

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

Schema description coverage is 100%, so the three parameters (organization_id, resource_id, idempotency_key) are already documented in the schema. The description adds no syntax or format detail beyond what the schema 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 opens with 'Request assisted DNS setup', a clear verb and action, but 'assistance' is vague and it does not distinguish this tool from sibling commsharbor_email_domain_setup or commsharbor_email_service_request. An agent cannot tell why to pick this over those siblings from the description alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling tool is named as an alternative despite several plausibly overlapping siblings (domain_setup, service_request). The agent must infer context from the name and schema.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real context beyond them: this registers an ownership challenge, and it discloses that mailbox passwords, message content and the private service credential are never returned. It stops short of saying what happens to an existing domain or what the challenge response is.

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

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

Four short clauses, purpose front-loaded, then permissions, then data-handling caveats. No filler, though the permission sentence is dense and slightly out of place for a create call.

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

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

With no output schema, the description should carry return-value expectations, and it only tells the agent what is *not* returned. It never describes the ownership challenge payload or the logical next step (verification), leaving a gap for a three-parameter mutation.

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 nothing about domain format, organization_id or the idempotency_key, so it does not improve on the schema's own 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 first sentence gives a specific verb and resource ('Register a domain and its ownership challenge'), so an agent can distinguish it from siblings like domain_get, domain_verify and domain_setup. It never explicitly names those alternatives, but the create-vs-read/verify split is inferable.

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 supplies an access model ('No guest access. Members can read. Owners, admins and organization keys can manage email') but frames it as permissions rather than when to call this tool instead of domain_verify or domain_setup. Usage is implied, not routed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: permission tiers per role and the security guarantees that the private service credential stays server-side and that mailbox passwords and message content are never returned.

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

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

Four short sentences, purpose front-loaded, then access rules, then data-exposure guarantees. Nothing is redundant, though the role list is slightly compressed into one dense sentence.

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

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

With no output schema, the description carries the return burden and names what comes back (setup, DNS records, readiness) while covering auth and data-exclusion rules. It stops short of describing structure or freshness of the 'observed readiness' data.

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 (organization_id, resource_id) are documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or lookup guidance for either identifier.

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?

Specific verb ('Read') plus a concrete resource bundle ('domain setup, DNS records and observed readiness'), which clearly separates it from mutation siblings like commsharbor_email_domain_create, commsharbor_email_domain_setup and commsharbor_email_domain_verify. An agent can tell this is the read/inspect counterpart without opening the schema.

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

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

The description gives access context ('No guest access. Members can read. Owners, admins and organization keys can manage email.'), which effectively tells the caller whether they can invoke it. However it never states when to prefer this over domain_verify, domain_assistance, or workspace_snapshot, so the sibling selection is left to inference.

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

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

The description asserts 'Association is idempotent', while the annotations declare idempotentHint=false — a direct contradiction. The 'Read or associate' framing also sits awkwardly against readOnlyHint=false. The behavioral claim the agent would rely on is at odds with the structured metadata.

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?

Five short sentences, but two of them restate the same idea ('Native product access must be enabled' vs 'Selected native products must already be enabled') and the sentence about the private email backend confirming ownership is opaque and does not clearly advance the agent's understanding. Moderate redundancy and weak front-loading.

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

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

For a mutation tool with no output schema, the description leaves important gaps: whether re-adding an already-associated product errors or no-ops, what permissions are needed, and how it differs from products_list. Combined with the idempotency contradiction, an agent lacks a reliable basis for calling it.

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

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

Schema coverage is 100%: services (pageaudit/hookpulse, maxItems 2), resource_id (email domain ID) and organization_id are all documented in the schema. The description names the two products and the domain/org targets, adding nothing beyond what the schema already provides, so the baseline 3 applies.

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

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

The description names the resource (PageAudit/HookPulse products) and the target (a domain in an organization), but opens with 'Read or associate', which conflicts with the tool name's 'add' verb and the existence of a sibling commsharbor_email_domain_products_list. An agent cannot cleanly tell whether this reads state or mutates it.

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 states prerequisites (native product access enabled, domain ownership confirmed, products already enabled), which implies the conditions under which the call will succeed. However, it never distinguishes this tool from the sibling products_list or setup tools, so alternative routing is left to inference.

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

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

Annotations declare readOnlyHint=true, yet the description says it will 'associate PageAudit and HookPulse with a domain' and that 'association is idempotent' – describing a state mutation. This directly contradicts the read-only annotation, so the agent cannot trust whether calling this changes state.

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 purpose is front-loaded, but the five short sentences are partly redundant – 'Native product access must be enabled' and 'Selected native products must already be enabled' overlap heavily, and neither earns its separate line.

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

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

There is no output schema, so the description should explain what a 'list' returns, yet it never states the return shape or ordering. Combined with the read/write contradiction, the definition is not complete enough for an agent to call it confidently.

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

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

Schema coverage is 100% and both parameters (organization_id, resource_id) are documented in the schema. The description only obliquely reinforces org scoping with 'in this organization' and adds no format or source details beyond the schema, 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 name and title say 'products_list' (a read), but the description leads with 'Read or associate PageAudit and HookPulse with a domain,' a dual verb that makes the actual operation ambiguous. It never disambiguates from the near-identical sibling commsharbor_email_domain_products_add, so an agent cannot tell which tool to pick for listing vs. adding.

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 lists preconditions ('Native product access must be enabled', 'Selected native products must already be enabled'), which is useful, but gives no when-to-use guidance, no when-not, and never references the sibling _products_add tool that appears to do the same association. The agent is left to infer when this tool applies.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: access is gated to callers who can open the organization, it returns "existing: null" on denial, credentials stay server-side, and mailbox passwords/message content are never exposed. This is genuinely useful behavioral disclosure, though it stops short of describing the exact return 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?

The description is tightly front-loaded with the action first, then return behavior, then access and privacy notes; every fragment carries information. The telegraphic style ("No guest access. Members can read.") is slightly choppy but wastes no words.

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

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

With no output schema, the description usefully sketches the return (org and domain IDs, or existing: null) and covers the authorization model. For a two-parameter read tool with readOnly annotations, this is close to sufficient, missing only the precise return field structure.

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

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

With only 50% schema coverage, the description must compensate – and it does not. The schema documents organization_id ("Organization ID") but leaves "domain" bare, and the description adds no format guidance (bare domain vs FQDN) or constraints for either parameter, leaving the agent to guess the expected domain syntax.

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

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

"Find an existing domain" states a recognizable action and the return payload (organization and domain IDs, or null), so the core purpose is legible. However, the name/title say "setup," which implies configuration rather than lookup, and the description never distinguishes this from the sibling commsharbor_email_domain_get. The mismatch plus missing sibling differentiation holds it at a minimum-viable 3.

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

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

The description explains permission tiers ("No guest access. Members can read. Owners, admins... can manage") but never states when to pick this tool versus email_domain_get, email_domain_create, or email_domain_verify. There is no when/when-not routing or prerequisite framing, so an agent must infer usage entirely.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds real context beyond that, disclosing that the call is an asynchronous 'queue' rather than an inline check, that the private service credential is never exposed, and that mailbox passwords and message content are not returned. It still does not say whether the result is a job handle or how to retrieve the outcome.

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?

Purpose is front-loaded and there is little padding, but the three terse permission sentences ('No guest access. Members can read. Owners, admins and organization keys can manage email.') read as pasted fragments and partially overlap, mildly diluting the core message.

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

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

For an async queue operation with no output schema, the description should explain what the caller receives and how to follow up, but it omits any reference to polling (e.g. via commsharbor_email_job_get). The permission model and data-exposure guarantees are covered, so it is adequate but has a clear gap around the async lifecycle.

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 organization_id, resource_id and idempotency_key are already documented in the schema. The description adds no syntax, format, or constraint detail (e.g. what makes an idempotency_key stable or valid), so baseline 3 applies.

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

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

The opening clause 'Queue a check of ownership, DNS and certificates' gives a specific verb (queue) plus the concrete checks performed, which is more informative than the tautological name 'email_domain_verify'. It does not explicitly contrast itself with siblings like domain_setup or domain_get, so an agent must infer the boundary from the name alone.

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

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

The description never states when to call this tool versus domain_setup, domain_get, or domain_assistance, nor what prerequisite state (e.g. domain must exist) is required. The permission sentences describe who is authorized but not the triggering condition or ordering, leaving usage entirely implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious context: that an organization key cannot authorize Google access, that the owner's account session is required, and that Google tokens stay encrypted server-side. These are real behavioral facts beyond the structured fields.

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 purpose is front-loaded, which is good, but the session requirement is stated twice ('Requires the owner's account session' and 'Requires an account session in this organization'), which is redundant. Sentence fragments are efficient but the repetition costs some tightness.

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

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

With no output schema, the description should carry more of the return-value burden; 'Reads site metadata only' gives only a hint about what the catalog contains. Auth and ownership caveats are well covered, but the actual shape/scope of what is returned is left thin for a 2-param read tool.

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

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

Schema description coverage is 100%, so organization_id and the service enum are already fully documented in the schema. The description adds no format, default, or interpretation detail for either parameter, 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?

The description states a read operation on 'authorized Google metadata' and 'site metadata', which gives a rough sense of the resource. However, it never explains what a 'catalog' returns (e.g. a list of connected Google services) and does not distinguish this from siblings like google_connect, google_resolve, or google_disconnect. The purpose is implied but not pinned down.

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 implicitly tells the agent when not to reach for this tool ('This does not prove DNS ownership'), hinting that domain verification is handled elsewhere. It also states the account-session prerequisite, which constrains usage. But it never names an alternative sibling or explains when this catalog read is the right choice versus google_connect/resolve.

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

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

Annotations only mark it non-read-only, non-idempotent, non-destructive, which is minimal. The description adds substantial behavioral context beyond that: a five-minute consent window, PKCE, that it returns an authorization URL, that a normal sign-in does not grant this access, the account-session/organization-key authorization rules, and that access and refresh tokens stay encrypted server-side. This is exactly the kind of auth and side-effect disclosure the annotations omit.

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?

Efficient overall and front-loads the core action, but there is redundant phrasing: 'Signing in does not grant this access' overlaps with 'Requires the owner's account session,' and the session requirement is restated twice ('owner's account session' then 'account session in this organization'). The sentences read as an accumulated list rather than a structured statement of action, prerequisites, and result.

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

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

With no output schema, the description correctly states the return value (an authorization URL) and covers the authorization prerequisites thoroughly. The main omission is any note on repeat/invalid invocations given the non-idempotent annotation, but for a consent-initiation tool this is close to 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%, with enums for service and language documented in the schema itself, so the baseline is 3. The description adds no parameter-level detail (no explanation of language, or of the two service values) beyond what the schema already 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?

States a specific verb and resource: it starts the Google consent (OAuth) flow with PKCE and returns an authorization URL. This clearly separates it from siblings like commsharbor_email_google_disconnect or commsharbor_email_google_resolve, though those siblings are never named explicitly. Purpose is unambiguous even if sibling differentiation is left implicit.

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 supplies real prerequisites (owner's account session required, an organization key cannot authorize, account session within this organization), which is valuable context. However it never states when to choose this tool versus commsharbor_email_google_resolve or _disconnect, nor what to do after obtaining the URL. Usage is implied via constraints rather than stated as when/when-not.

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

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

Annotations only give the generic flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantive behavior beyond that: what is destroyed (connection + pending consent), what survives (existing email/service resources, encrypted tokens on the server). It does not address re-invocation/error behavior despite idempotentHint=false.

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

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

Front-loaded and generally tight, but 'Requires an account session in this organization' restates the earlier session requirement, and 'Reads site metadata only' reads as a stray, context-mismatched fragment that adds noise without 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 two-param mutation with no output schema, the description covers authorization, blast radius, and what is preserved — enough to call it safely. Only idempotency/failure behavior is left unaddressed.

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 enum for 'service' is already documented with per-connection consent semantics in the schema. The description adds nothing about organization_id or the service enum, so the schema does all the work — baseline 3.

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

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

States a specific verb+resource: 'Remove this product's saved Google connection and pending consent.' The scope words ('this product's', 'pending consent') make it meaningfully distinct from the sibling commsharbor_email_google_connect, but no sibling tool is named explicitly, so the differentiation is inferred rather than stated.

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

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

Gives real invocation preconditions: an owner's account session is required and an organization key cannot authorize Google access. It never names an alternative (connect, resolve, catalog) or states when-not-to-use, so it stops short of full 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?

With sparse annotations, the description adds real behavioral context: authentication requirements (owner session, org key insufficient), that it only reads site metadata, and that Google access/refresh tokens stay encrypted server-side. Note a mild tension: "Reads site metadata only" reads as read-only while readOnlyHint=false, though false is the conservative default and resolve may refresh tokens, so this is not a true contradiction.

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

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

Purpose and the Search Console exclusion are front-loaded, but the body is a run of short fragments with redundancy: "Requires the owner's account session" and "Requires an account session in this organization" say nearly the same thing. Some trimming would tighten it without losing meaning.

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, the description covers scope, auth prerequisites, service routing, and data-handling behavior, which is close to sufficient. What the resolve step actually returns (property-to-URL mapping) is implied rather than stated, a minor gap given no output schema exists.

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 service, properties (min/max/unique) and organization_id; the baseline is 3. The description only echoes the 20-property cap and hints that the service enum matters, adding little beyond the structured fields.

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 (resolve website addresses for selected Analytics properties) and bounds the scope (up to 20 properties), which is enough to distinguish it from generic sibling calls like google_catalog or google_connect. It does not name the nearest siblings it complements, 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?

It gives an explicit exclusion ("Search Console does not use this route") plus preconditions (owner's account session required, organization key cannot authorize Google access). It lacks a positive statement of when to prefer this over google_catalog/google_connect, so it falls just short of full 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds real value beyond that: authorization tiers (guest/member/owner/admin/org key), handling of the private service credential, and an explicit data-disclosure boundary ('Mailbox passwords and message content are never returned'). The lack of any error/not-found behavior keeps it just short of a 5.

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?

Five short sentences, front-loaded with the core action before the access and data rules. Dense but each clause carries information. The 'private service credential stays on the server' line is tangentially relevant to the caller and slightly boilerplate, keeping it from 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?

No output schema exists, so the description carries the burden of describing returns, and it does disclose the key negative case (no mailbox passwords or message content). For a simple two-param read tool with full annotation coverage, this is nearly complete; only the shape of a successful 'job' response and not-found behavior are unaddressed.

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 carry inline descriptions, so the schema already does the heavy lifting. The description adds no syntax, format, or meaning beyond the schema for organization_id and resource_id, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Read one durable job in this organization'. The scope (single job, current organization) is clear, and it is distinguishable from write-oriented siblings like mailbox_create or domain_create. However, it does not define what a 'job' is or contrast itself with other read siblings such as organization_get or domain_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?

Provides access-condition guidance ('No guest access. Members can read. Owners, admins and organization keys can manage email'), which tells the agent who is allowed to call it. It does not state when to use this tool versus alternatives or what prerequisites (e.g. a valid job/resource_id) are needed, so usage is only implied.

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

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

Annotations only declare it is a non-read-only, non-idempotent, non-destructive write. The description adds substantial context beyond that: trial mailboxes share 1 GB and cannot send, no guest access, the read/manage role split, the service credential staying server-side, and that passwords and message content are never returned. That is exactly the kind of disclosure annotations cannot carry.

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 purpose is front-loaded in the first clause and every following sentence carries distinct information (trial limits, access model, permissions, secret handling). It is longer than typical but not padded; the telegraphic sentence fragments slightly hurt readability rather than length.

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

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

For a five-parameter mutation with no output schema and minimal annotations, the description covers scope, quota behavior, authorization and data-handling expectations. It stops short of describing what is returned on success or how the required idempotency_key is honored, which matters given idempotentHint=false.

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% (all five parameters documented, including local_part, domain_id and idempotency_key), so the schema already does the parameter work and the baseline is 3. The description adds no per-parameter semantics such as local_part formatting rules or what the allowance actually constrains.

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

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

States a specific verb and resource ("Create a mailbox") and scopes it with "within the current allowance", which separates it from the update/suspend/resume/password siblings on the same resource. It does not explicitly name a sibling or state when creating a mailbox is preferred over an alias, but the resource noun 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?

"Within the current allowance" implies a quota precondition, and the permission sentence ("Members can read. Owners, admins and organization keys can manage email") implies who may call it, but neither is framed as an explicit when-to-use rule. No alternatives or exclusions are named, so the agent must infer selection from the resource name alone.

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

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

Annotations only say the operation is a non-read, non-idempotent, non-destructive write. The description adds the material context the annotations lack: the password is encrypted for the executor, never returned, guest access is excluded, members get read-only access while owners/admins/org keys may manage, and the private service credential stays server-side.

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?

Purpose is front-loaded, but the body is a stack of terse fragments and the never-returned point is stated twice ("is never returned" and "Mailbox passwords and message content are never returned"). The line about the private service credential is generic security boilerplate that does not directly serve this call.

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

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

For a parameterized write with no output schema and thin annotations, the description covers the key agent questions: secrecy of the value, who is authorized, and that no secret is echoed back. It omits what happens to the prior password and how idempotency_key behaves, which keeps it from a 5.

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 four parameters (password length/charset rules, resource_id, organization_id, idempotency_key) are already documented in the schema. The description adds no per-parameter meaning beyond that, so the baseline 3 applies.

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

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

"Set the mailbox password" is a specific verb+resource that clearly separates this tool from sibling mailbox_create, mailbox_update, mailbox_suspend and mailbox_resume. It does not explicitly name a sibling it differs from, so it stops short of a 5.

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

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

Usage is implied by the purpose (rotating/setting a mailbox password) and the permission sentence ("Owners, admins and organization keys can manage email") tells the agent who may call it. There is no statement of when to use this instead of mailbox_update, nor any prerequisite/exclusion 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?

Annotations only supply the safety flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real value beyond them: the permission tiers (guests excluded, members read-only, owners/admins/org keys manage), the fact that the private service credential never leaves the server, and that passwords/message content are never returned. It does not explain reversibility or the effect on the suspended state itself, keeping it short of a 5.

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

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

Front-loads the action in the first sentence, then uses terse sentences for permissions and security guarantees. No filler, though the short clipped fragments are a bit telegraphic rather than smoothly 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?

With no output schema, the description sensibly covers what is and isn't returned (no passwords, no message content, credential stays server-side) and who may invoke it. Missing only the relationship to the sibling suspend/alias tools and any note on return shape, so it is close to complete for a state-change 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 organization_id, resource_id and idempotency_key are already documented in the schema. The description adds no syntax, format, or inter-parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource: "Restore suspended mailbox access." That is clear and actionable. It does not, however, distinguish itself from the sibling commsharbor_email_alias_resume, so an agent choosing between resuming a mailbox vs an alias gets no routing help from the text.

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 context through constraints ("No guest access. Members can read. Owners, admins and organization keys can manage email"), which tells the agent when the call will succeed permission-wise. It never states when to use this tool versus the sibling alias resume/suspend tools, so 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description goes further: it confirms data preservation, states that guest access is excluded and members retain read access, and discloses that credentials stay server-side and passwords/message content are never returned. This is meaningful context beyond the annotations. It does not address idempotency behavior despite a required idempotency_key, which is a notable omission.

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

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

The purpose is front-loaded in the first sentence, which is good. However, the trailing sentences about the private service credential and never-returned passwords read as generic service boilerplate that may not earn its place in a single-mutation tool description, making it slightly padded rather than tight.

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 three-required-parameter mutation with no output schema, the description covers behavior and permission context adequately. It leaves gaps on when to prefer this over resume/delete, and it never explains the required idempotency_key even though annotations declare idempotentHint=false, which is a genuine ambiguity an agent would want resolved.

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 resource_id, idempotency_key, and organization_id are already documented by the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

The opening sentence names a specific verb and resource ('Suspend access' on a mailbox) plus the key side effect ('while preserving mailbox data'), which immediately distinguishes it from a delete. It does not explicitly name the counterpart sibling (commsharbor_email_mailbox_resume) or clarify suspend vs. alias_suspend, so it falls short of full sibling differentiation.

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

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

Usage is only implied: an agent can infer this is the tool to disable a mailbox reversibly, but there is no explicit 'use this when / use resume instead' routing and no stated prerequisites for when suspension is appropriate. The permission sentence ('Owners, admins and organization keys can manage email') is closer to auth policy than to 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?

Annotations already flag destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is known. The description adds genuinely non-schema context: the permission tiers, that the private service credential is server-side only, and that passwords/message content are never returned — useful for a mutation tool. It does not, however, explain what the update destroys or whether quota reductions affect existing mail.

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?

Five short sentences, front-loaded with the operation and its scope before the permission and security notes. Little waste, though the closing security guarantees are somewhat boilerplate and repeat across the family.

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

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

For a destructive update with no output schema and fully documented parameters, the description supplies the missing authorization and data-exposure context an agent needs. Counting on the schema for parameter detail and annotations for the destructive flag, the remaining gap is only the effect of a quota change on existing content.

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 six parameters (including the plan-fitting constraints on quota_mb and files_quota_mb) are already documented in the schema. The description only echoes 'name or quota' and adds no syntax, units, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The first sentence gives a specific verb and resource ('Change mailbox name or quota') and scopes it to the plan, which is enough to distinguish it from sibling mailbox tools like create/suspend/resume. It stops short of naming a sibling alternative, but the target 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?

Usage is only implied: the description states the authorization model ('No guest access. Members can read. Owners, admins and organization keys can manage email'), which tells an agent who may call it but not when to choose it over mailbox_create or mailbox_suspend/resume. No exclusions or alternative routing 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?

Annotations cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: 10-minute result caching, a 30-new-checks-per-day-per-network rate limit, common-selector-only DKIM lookup, and the meaning of the `incomplete`/`unread` failure semantics. This is exactly the operational detail annotations cannot express.

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?

Purpose is front-loaded, followed by operational limits and interpretation caveats, each sentence earning its place. It reads as a dense run-on paragraph, but no content is redundant with structured fields.

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

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

With no output schema, the description carries return-value burden and does so well: the 0-100 score, fixes ordered most-severe-first, and the precise meaning of `dkim_not_found`, `incomplete: true`, and `unread`. An agent can interpret results correctly without any further documentation.

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

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

Schema coverage is 100% with a single documented `domain` parameter, so the schema already does the work and baseline is 3. The description reinforces the domain concept but adds no format or syntax detail beyond what the schema states.

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

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

States a specific verb (check) and resource (email sendability of a domain), then enumerates exactly what is probed: SPF, DKIM, DMARC, MX, MTA-STS, BIMI, plus the 0-100 score and fixes. It is unmistakably distinct from the CRUD-oriented sibling tools like email_domain_get or email_domain_verify.

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: 'Public DNS only. Free, no account,' establishing this as a no-auth diagnostic step. It does not name an alternative or state a when-not condition, but no sibling overlaps enough to require routing, so the missing exclusion is minor.

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 annotations covering the safety profile, the description adds real value: it discloses role/permission constraints and states explicitly that the service credential stays server-side and that mailbox passwords and message content are never returned. It does not explain what 'activation on demand' produces, nor whether a repeated call with the same idempotency_key is deduplicated — notable given the required idempotency_key and idempotentHint=false.

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?

Short and front-loaded, with the core action in the first clause. The clipped sentence fragments ('No guest access. Members can read.') are information-dense but slightly telegraphic.

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

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

For a mutation tool with no output schema and three required params, it covers permissions and data-exposure limits, which is useful. It leaves gaps around what the request returns or triggers — it does not mention the sibling commsharbor_email_job_get, so an agent cannot tell whether this is async and needs polling.

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 each parameter carries its own description, so the schema does the heavy lifting. The description adds no format, enum, or idempotency-key semantics beyond what the schema already provides; baseline 3 applies.

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

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

The description states a specific verb+resource ('Request an included service with activation on demand'), which tells an agent what the tool does. It does not, however, distinguish itself from adjacent siblings such as commsharbor_email_trial_activate or commsharbor_email_domain_products_add, which also provision services/add-ons.

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

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

It gives an access-control context ('No guest access. Members can read. Owners, admins and organization keys can manage email'), which implies who may invoke it. It never states when to choose this over trial_activate or domain_products_add, nor what prerequisites (e.g. an existing plan) are required.

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?

Goes well beyond the annotations by disclosing trial duration, quota, that outgoing SMTP and external forwarding are disabled, role-based access (members read; owners/admins/org keys manage), guest access exclusion, and a security guarantee that the service credential and mailbox passwords/content are never returned. It does not explain what happens on re-invocation, which is notable given the required idempotency_key alongside idempotentHint=false.

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

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

Front-loads the core action, duration, and quota before the constraints, and every sentence carries information. It is a dense single paragraph with security and permission clauses that are useful but slightly tangential to invocation.

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

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

For a mutation with no output schema, the description covers effect, limits, prerequisites, and side effects thoroughly. The one missing piece is idempotency behavior: a required idempotency_key is never explained, and annotations declare idempotentHint=false, which an agent cannot reconcile from the 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% for both parameters, so baseline is 3. The description adds organizational context ('new workspace', 'operator-proved native quota') but no syntax, format, or meaning for organization_id or idempotency_key beyond the schema.

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

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

States a specific verb ('Start') plus a precisely bounded resource: 'the free receive-only Trial for 7 days, once per organization'. The receive-only scope and 7-day/1 GB limits immediately distinguish it from sibling provisioning tools like commsharbor_email_workspace or commsharbor_email_service_request.

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

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

Gives real preconditions - 'once per organization', 'Requires a new workspace and operator-proved native quota' - which tell the agent when the call will succeed. It does not name an alternative tool or an explicit when-not-to-use case, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered elsewhere. The description adds real value on top of that: role-based access tiers, that the private service credential stays server-side, and that mailbox passwords and message content are never returned.

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?

Five short, front-loaded sentences that lead with the action and then layer on access and disclosure constraints. No filler, though the access-tier sentence is slightly more detail than strictly needed to select the 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?

With no output schema, the description partially compensates by stating what is never returned (mailbox passwords, message content) and who can call it. It stops short of describing what the workspace read actually yields, which is the one gap for a tool with no output schema.

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

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

Single parameter with 100% schema description coverage, so the schema fully documents organization_id. The description adds nothing about the parameter's meaning or accepted format, which matches the baseline for a fully covered schema.

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

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

States a specific verb and resource ('Read the email workspace'), which is more than a restatement of the title. However, it never distinguishes itself from the closely named sibling commsharbor_email_workspace_snapshot, so an agent cannot tell from the description alone which read tool it wants.

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 lays out a useful access model (no guest access, members read, owners/admins/keys manage), which implies who may call it. But there is no explicit when-to-use guidance and no routing to alternatives such as the snapshot, mailbox_get, or domain_get siblings.

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

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

Annotations already establish the safe read-only, idempotent profile, so the description clears the lower bar. It adds real behavioral context beyond annotations: membership is re-validated per snapshot, events carry only an opaque change ID, and DNS checks run in the private backend on a 24-hour deadline with a visible resume action after pause. Return-format detail (pagination, snapshot size) is still absent.

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

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

Four sentences, front-loaded with the core read behavior before the scoping and DNS details. Nothing is redundant, though the DNS-deadline sentence is somewhat tangential to tool selection and could be condensed.

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

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

For a single-parameter read tool with no output schema, the description covers identity scoping, membership re-checks, event shape, and backend DNS behavior. The main missing piece is any differentiation from the sibling workspace tool, which the agent needs to choose 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?

Only one parameter, and schema coverage is 100% with the schema describing it as 'Selected organization ID', so the baseline is 3. The description adds a genuine constraint not in the schema: the ID must match the X-Organization-Id header, which changes how an agent must source the 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?

States a specific verb and resource set: read the current email workspace plus DNS progress and recent jobs. An agent knows exactly what surface is returned. However, it never distinguishes this from the sibling commsharbor_email_workspace, leaving the agent to guess which one to pick.

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 content listing (workspace state, DNS progress, recent jobs) and by the requirement that the ID match X-Organization-Id. There is no explicit when-to-use/when-not or routing to the near-identical commsharbor_email_workspace sibling, which is the biggest selection risk here.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety and repeatability are covered. The description adds the propagation nuance (commit appearing here), which is useful behavioral context, but it does not describe the response contents or any latency characteristics beyond the vague propagation note.

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

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

Two short sentences with the core purpose front-loaded. The second sentence is somewhat jargon-heavy ('racing edge propagation') but is compact and adds intent rather than padding.

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

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

With no output schema, the description carries the burden of explaining the return value, and 'deployment health and build' is not concrete about what fields or statuses come back. For a health-check tool whose whole value is interpreting the response, this is a meaningful but not fatal gap.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline of 4 applies since parameter semantics are trivially complete.

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: 'Read deployment health and build.' This is distinguishable from the many sibling management tools, though it does not explicitly differentiate itself from adjacent smoke/operations tools like commsharbor_domain_smoke or commsharbor_operations. Clear but not sibling-routing.

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 second sentence implies usage context ('Smoke tests wait for their own commit to appear here instead of racing edge propagation'), which tells the agent this is a polling/target for verification flows. However, there is no explicit when-to-use versus when-not guidance or named alternative tool, so usage is implied 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?

Annotations only declare the mutation/safety profile (readOnly=false, idempotent=false, destructive=false); the description adds real behavioral value by disclosing the CSRF/bootstrap prerequisite and, importantly, that only the current session is revoked while other product sessions remain active. It does not cover error behavior or whether re-authentication is required.

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

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

Three short sentences, front-loaded with the action, then prerequisite, then side-effect scope. No filler and each sentence carries distinct 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 zero-param state-changing action with no output schema, the description covers the prerequisite and the blast radius, which is the key information an agent needs. Minor gap: no mention of failure modes or post-logout state of the caller.

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 takes zero parameters, so the baseline is 4. The description correctly implies no arguments are needed and instead documents the ambient credential context the call relies on.

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 ('Revoke the current session') with the exact scope of the operation. No sibling tool competes with logout, so the purpose is unambiguous on its own.

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 it applies by describing the required bootstrap/CSRF context, but it never states when to call it versus when not to, or what happens if the prerequisite is missing. There is no alternative tool for this action, so the guidance gap is modest rather than severe.

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

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

Annotations already establish readOnly and idempotent behavior, so the bar is lower, and the description still adds value: it identifies `user.id` as the shared-account ID and discloses a scope boundary (organizations are not returned here). It does not cover auth requirements or the full shape of the returned profile.

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 purpose is front-loaded in a tight first sentence, but the second sentence is long and circuitously worded ('live in the shared account, which does not list them inside products yet'), stacking two related scope caveats into one dense clause. It is not padded, but it is harder to parse than it needs to be.

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

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

There is no output schema, so the description carries the return-shape burden. It names the profile, the platform role and `user.id`, but does not indicate what else a profile contains (e.g. email, name, role values), leaving the agent without a full picture of the response.

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 takes zero parameters, so there is no parameter surface to document. Baseline for a parameterless tool is 4, and the schema coverage signal is effectively moot.

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

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

The first sentence states a specific verb and resource: read the current account profile and platform role. That cleanly separates it from CRUD-style siblings like commsharbor_organization_get and campaign/contact tools. It stops short of naming the closest siblings (commsharbor_context, commsharbor_platform_context), so it is clear but not fully differentiated.

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 explicitly states a when-not: organizations are not listed here, and routes the agent to the organization-by-ID call. The alternative is given as an API path rather than the sibling tool name, so the routing is clear but requires the agent to map path to 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: name and role derive from the shared account and are null when using an organization API key, and the plan is a global entitlement. That conditional return behavior is not derivable from the schema or annotations.

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

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

Three sentences, front-loaded with the purpose and return fields, then the conditional null behavior. Dense but each sentence carries information; 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?

With no output schema, the description does the work of describing the return shape (name, role, plan) and the API-key edge case. An agent has enough to invoke it correctly and interpret results, though it could say more about error cases when the id is invalid or inaccessible.

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

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

Schema coverage is 100% for the single organization_id parameter, so the schema already documents it as the 'Active organization ID'. The description's 'by id' phrasing adds nothing beyond that, making the baseline 3 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?

States a specific verb ('open') and resource ('an organization by id') and enumerates what it returns: name, your role, and the CommsHarbor plan. It is distinguishable from siblings like commsharbor_me or commsharbor_context, though it never names those alternatives.

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

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

'This is how a workspace is opened' implies the tool is the entry point for starting work in an organization, which is useful context. However, there is no explicit statement of when to use this versus commsharbor_me, commsharbor_context, or the plural listing siblings, and no prerequisites or 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond them by disclosing the authorization model: platform access is an explicit grant independent of tenant ownership, which materially affects whether a call will succeed.

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

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

Two tight sentences with the core assertion front-loaded and the authorization caveat second. Nothing is wasted, though it is sparse enough that it could afford one more clarifying clause.

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

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

With no output schema, the description carries the burden of explaining what is returned, and it only says the role is 'confirmed' without describing the shape of the result. The authorization context is helpful but the return contract is left 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 tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline of 4 for a parameterless 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?

States a specific verb ('Confirm') and resource ('the caller's platform role'), so the purpose is legible at a glance. It does not, however, distinguish itself from near-siblings like commsharbor_context or commsharbor_me, leaving an agent to infer that this is the platform-level variant.

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 line 'Tenant ownership grants nothing here: platform access is a separate, explicit grant' implies when this tool matters (platform-level checks, not tenant checks), but it names no alternative and gives no explicit when/when-not routing. Usage is only implied.

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