openpanel_merge_profiles

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

No annotations are provided, so the description must carry the full burden. It mentions 'merge' but provides no details on side effects: whether the secondary profile is deleted, if the operation is reversible, how data conflicts are resolved, or required permissions. This is inadequate for a likely destructive operation.

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

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

The description is brief, but the '[UNIFIED]' prefix appears to be metadata or a category tag leaking into the description, adding noise without value. The remaining sentence is efficient but arguably too terse given the operation's complexity.

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

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

For a 4-parameter, likely destructive operation with zero schema annotations and no output schema, a single sentence is insufficient. The description lacks essential context about merge mechanics, data handling, and success/failure behaviors required for safe invocation.

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 0% schema description coverage, the description needs to compensate significantly. While it implies the existence of two profile parameters, it offers no explanation for 'site', 'project_id', or the critical distinction between 'primary' and 'secondary' (which determines data survivorship).

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

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

The description clearly states the tool merges two user profiles and specifies the use case (duplicate resolution). However, it does not clarify which profile survives the merge or what 'merge' entails specifically, slightly limiting its distinctiveness from update/delete 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?

It mentions the specific use case (duplicate resolution), providing basic context for when to use it. However, it fails to mention prerequisites (e.g., verifying duplicates), when NOT to use it, or alternatives like openpanel_delete_profile for non-duplicate scenarios.

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