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

With idempotentHint=true and destructiveHint=false already declared, the description adds substantial behavior beyond annotations: writes over a hard cap are REJECTED rather than truncated (telling the agent to shorten, not retry), empty strings clear fields, outreachIntents uses replace-not-merge resolution with fallback to wider scopes, and playbook sections are selected per message. This is exactly the kind of operational detail an agent needs to avoid failed calls.

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

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

The description is long but every sentence earns its place — the offerContext/capabilities distinction is essential and non-obvious, and the character-cap warning prevents a whole class of failed writes. It is front-loaded with the core partial-update semantic, then organized logically by parameter. The outreachIntents detail is deferred to the schema description, which keeps the main description from bloating further.

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 9-parameter mutation tool with nested objects and no output schema, the description covers the high-risk aspects: error behavior, clearing semantics, override resolution, and what not to include in playbook sections. Minor gaps remain — no mention of what the response looks like on success, whether empty strings clear the simple fields, or auth requirements — but the critical decision points for a correct call are addressed.

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

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

Schema coverage is only 22%, so the description carries the burden — and it earns its keep on the three genuinely ambiguous parameters: offerContext (factual grounding injected into every craft), capabilities (system detection abilities injected into replies only, never a pitch list), and playbookSections (per-section char caps with target lengths). The self-evident params (name, industry, companyName, companyWebsiteUrl, workspaceId) are left to their names, which is an acceptable trade given the description cannot cover all nine at this length.

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

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

The description opens with a specific verb and resource ('Update workspace settings') and immediately clarifies the partial-update semantics ('Only provided fields are updated'). It clearly identifies the operation, though it does not explicitly differentiate itself from closely named siblings like campaignstack_update_workspace_branding or campaignstack_get_workspace; the agent must infer the boundary from the name.

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

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

The description gives strong contextual guidance about when field values are consumed (injected into crafts, reply crafts only, per-message selection) and explicitly points to campaignstack_get_playbook for reading current values before updating. However, it never states when NOT to use this tool or names alternatives for branding/workspace-level reads, so the when-to-use is largely 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.