get_incentive

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

With no annotations, the description carries full burden. It clarifies that the tool returns a draft incentive, and provides specific details about the conversion_id being a draft UUID and how trigger IDs are used. It implies read-only behavior but does not explicitly state no side effects.

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 three sentences plus an example, conveying key information efficiently. It packs in details about trigger IDs, but could be slightly more structured. No extraneous content.

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 simple retrieval tool with two parameters and no output schema, the description provides sufficient context: what the tool does, parameter semantics, and an example. It does not cover return format, but that is acceptable given no output schema. It feels complete for its complexity.

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 50% (only conversion_id has schema description). The description adds meaning by clarifying conversion_id is a 'draft conversion UUID from incentives API' and provides an example. This compensates for the missing project_id description and adds value beyond the schema.

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?

Tool explicitly states it 'Gets one draft incentive with scoped triggers', using a specific verb and resource. It distinguishes itself from list_incentives by mentioning 'same merge' and provides context about draft vs published trigger IDs.

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 implies usage when you need a single draft incentive and its associated trigger IDs, but lacks explicit when-to-use or when-not-to-use guidance compared to siblings like get_trigger or list_incentives. The hint about using draft_trigger_id for PATCH update_trigger is helpful but not a full guideline.

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