Create lead

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

With no annotations, the description carries the behavioral burden. It explicitly discloses a non-obvious side effect: 'contact created if missing'. It also surfaces the optional template-send behavior via templateMessageData factor. It does not cover auth, duplicates, or error cases, but the disclosed behaviors go well beyond the bare 'create' semantics.

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?

Two compact sentences, front-loaded with the core action a agent needs. The side effect and optional behavior are mentioned immediately, and the cross-reference is placed at the end. No wasted words.

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?

High complexity (17 parameters, nested objects, optional template send, no output schema) but the description is minimal. It does not explain required input prerequisites beyond what the schema already provides, does not describe return values, and lacks usage context. The pointer to gambot_get_lead_fields helps but is not enough for confident 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?

Schema description coverage is only 18%, so the description needs to compensate. It vaguely says 'Accepts all base lead fields' and points to gambot_get_lead_fields, but it does not explain the meaning of most parameters such as keys, tags, stageId, pipelineId, or priority. The parameter semantics are largely left to the agent to infer.

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 verb and resource: 'Create a CRM lead'. It adds meaningful scope details—contact auto-created if missing, optional template send, nested customFields—so it is clearly distinguishable from siblings like gambot_create_contact and gambot_update_lead.

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 on when to choose this tool over alternatives such as gambot_create_contact or gambot_send_template. The reference to gambot_get_lead_fields is about parameter discovery, not usage context. There are no exclusions or conditions stated.

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