gold_ghl_contacts_search_upsert_bulk

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

With no annotations, the description carries the full burden. It does communicate that the tool uses a user-provided GHL API key and that upsert is a write operation, but it omits the confirm guard, the 50-item cap, default action, and any outcome/return behavior. The 'PAID ONLY $39' line adds cost noise rather than operational transparency.

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 useful operations are front-loaded, but the middle clause about a 'dead 193-star repo' and the 'PAID ONLY $39' sentence do not help an agent invoke the tool correctly. The description could be half as long and lose only noise.

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 annotations or output schema exist, and the tool has two modes plus a confirmation gate, yet the description does not explain the confirm requirement, default action, location override, or what a caller should expect back. The schema fills some gaps, but the description alone is not complete for a mutating dual-mode 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 the baseline is 3. The phrase 'email key' adds a small bit of meaning by suggesting email is the identity key for upserts, but the description otherwise restates what parameter descriptions already cover.

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 a concrete resource and two explicit operations: 'Search contacts by query' and 'bulk-upsert an array (email key) with tags.' It is specific enough for an agent to know what the tool does, though it does not explicitly contrast it with sibling tools like gold_ghl_tags_bulk_apply.

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?

No guidance is given about when to choose search versus upsert_bulk, when to prefer a sibling tool, or what prerequisites exist beyond 'BYOK GHL_API_KEY.' The schema's action enum implies the two modes, but the description does not state decision criteria.

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