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

With readOnlyHint=false, destructiveHint=false and idempotentHint=true already set, the description still adds real behavioral information: a change preserves the earlier answer and can be restored from the Memory page, 'nothing is deleted', while start_over replaces rather than merges and earlier answers survive in History. It also discloses the openWorld behavior (website is read to draft the profile) and the sentinel return 'set_up_now' when the profile is not built.

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 content is front-loaded with the routing rule and the default read payload, which is good, but it arrives as one dense block with no separation between read behavior, onboarding flow, and update semantics. Sentences are overloaded (the step/ask_now/say_now clause in particular), so the agent must parse rather than scan. Little is wasted, but structure is poor for a 17-parameter, three-mode tool.

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

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

For a complex, no-output-schema tool it covers the full lifecycle: what a no-argument call returns, how the guided build proceeds one question at a time, how updates behave, and how a full replacement is triggered. The remaining hole is the ask_now/say_now protocol, which is described in prose but not tied to any schema parameter, leaving ambiguity about whether those are inputs or returned values.

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 59%, but the description compensates by defining most fields' meaning: clients are kept out of results and used as the fit picture, accounts are prospects not clients, website drives the draft, and several fields may be passed in one call. The step/skip interplay with ask_now and say_now is explained even though neither name appears in the schema, which is genuinely additive. A few fields (firm_name, territory, device_areas, notes) are only listed, not explained.

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 resource — the rep's own firm profile plus plan usage — and enumerates what it holds (services, clients, not-a-fit companies, saved watches, usage counters). 'Call this first for anything about the rep's own firm' cleanly separates it from sibling tools like company, find, or about_the_data. It loses a point for bundling three modes (read, guided profile build, field update) into one undifferentiated paragraph rather than naming them as modes.

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

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

It gives a clear entry rule ('Call this first for anything about the rep's own firm') and explicit triggers for the write paths: pass a field to change it, pass start_over with every detail for a different firm or a rebuild. It does not name the sibling that handles the same data in other contexts (e.g., forget for deletions, about_the_data for provenance), so the agent must infer the boundary.

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