Create opportunity

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

Annotations already declare readOnlyHint:false, openWorldHint:true, and idempotentHint:false, so an agent knows this call mutates state, may have side effects beyond provided params, and is not safe to repeat. The description adds the '(deal)' domain clarification and pipeline-stage context but discloses no additional behavioral traits (e.g., duplicate creation on retries or auth requirements) — acceptable given the annotated safety profile.

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 sentences with zero filler: the first states the action and scope, the second states the prerequisite call. Information is front-loaded with verb, resource, and context appearing immediately, and every sentence earns its place.

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 write operation with 8 parameters, 100% schema coverage, and annotations declaring read-write, open-world, non-idempotent behavior, the description covers the critical path: what is created and which tool to call first. The only gap is silence on what the call returns, which is minor for a create tool whose annotations already establish the side-effect profile.

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 100% and every parameter has a meaningful description, so the schema carries the explanatory burden, yielding the baseline 3. The description adds the dependency relationship between pipelineId/pipelineStageId and ghl_get_pipelines, which is useful, but provides no per-parameter meaning beyond what the schema already documents.

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?

Description states 'Create a new opportunity (deal) in a pipeline stage' — a specific verb (create), resource (opportunity), and context (pipeline stage), with the parenthetical '(deal)' anchoring domain terminology. The verb clearly distinguishes it from sibling tools like ghl_update_opportunity, ghl_get_opportunity, and ghl_search_opportunities, so an agent can select correctly.

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?

The description provides an explicit prerequisite: 'Use ghl_get_pipelines first to obtain valid pipelineId and pipelineStageId values,' which both instructs the agent and explains why the prerequisite matters. It does not, however, state when-not-to-use this tool versus alternatives (e.g., ghl_update_opportunity for modifying an existing deal), stopping short of a full 5.

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