smokeball_create_lead

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=true. The description adds useful operational context: the cause of routing through governed authority, that 'Spring verifies' the claimed read/write effect, and that approval_ref is needed when resuming a write. It does not contradict the annotations, but it also does not disclose what external side effects occur beyond 'create_lead', especially in light of the destructiveHint flag.

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 compact and well-structured: a single lead-in line followed by a bulleted parameter list. Each parameter has a short explanation, and there is no fluff or repetition of the schema. The only mild redundancy is restating the tool name in the first line.

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?

Even though an output schema exists, the description does not explain what the 'arguments' JSON should contain for a create_lead operation. This is the core payload needed to actually create a lead, yet the description only says 'JSON string of arguments for the connector operation.' There is no information about required lead fields, the Smokeball API shape, or how to construct a valid request. The platform parameters are covered, but the domain-level invocation context is missing.

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 0%, so the description carries the full burden for parameter semantics. It provides an explanatory line for all seven parameters, including the purpose of arguments (JSON string), idempotency_key (stable business-action identity), and approval_ref (approved platform task UUID for resuming a write). Some explanations are vague (project_ref as 'exact project correlation reference'), but they go well beyond the bare schema and help an agent understand the platform-level wrapper parameters.

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 says 'Smokeball connector operation `create_lead`' which essentially restates the tool name without explaining what a lead is or what the operation actually does. The added routing constraint 'Routes only through the exact project/account governed connector authority' is a platform restriction, not a purpose statement. It is clear enough from the name that it creates a lead, but the description itself does not add meaningful domain-level purpose beyond that.

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 use this tool versus alternatives such as smokeball_create_contact or smokeball_create_matter. The only contextual note is about routing authority, which is a constraint, not a usage guideline. There are no exclusions, prerequisites, or examples of appropriate scenarios.

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