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

Annotations only declare it is a non-read-only, non-destructive, closed-world mutation. The description adds substantial behavior beyond that: idempotency semantics (no topicId always creates a new identity even for the same title), retry preservation of title/description/scope/Client association, clientId matching rules, that no scan is launched and recurring schedules are unavailable, and that models patch account defaults only for new configurations. This is rich, decision-relevant disclosure.

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

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

Front-loads the core purpose well, but the body is a dense run-on that repeats 'use update_topic to edit' three times and interleaves creation, recovery, and update semantics. Every sentence is on-topic and information-dense, but structure and non-redundancy suffer noticeably.

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?

An output schema exists, so return values need not be explained, and the description still ties outputs to consumers ('shared report/config tools use the returned site.id as siteId'). For a 7-param tool with nested objects, it covers creation, recovery, association, model patching, prompts, and scan behavior thoroughly.

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

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

Schema description coverage is only 29%, so the description must carry the load, and it does: clientId (optional, null = standalone with Account access), strategicGoal (initializes an absent note, null clears on update), models (patches defaults, null clears selections, unspecified preserved), and topicId (recovery source). It also explains preservation behavior for name/description/scope. Minor remaining gap is the top-level description field, only alluded to via preservation language.

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

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

Opens with a specific verb and resource: create research about a subject scoped by name and topicProfile.scope, and explicitly distinguishes the no-website/business-profile variant. It also names the sibling it is not (update_topic) and the recovery source (topic_setup_incomplete), so the agent can situate it among siblings. Slightly jargon-heavy ('research', 'topicProfile.scope') but specific.

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?

Clearly states the two entry paths: new creation (name + topicProfile, optional clientId/strategicGoal/models) versus recovery via a saved siteId passed as topicId. It routes editing away with 'use update_topic to edit/replace/clear'. It stops short of contrasting with create_site or other creation siblings, so 4 rather than 5.

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