label_add

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

With no annotations, the description carries the full burden. It discloses the core behavior (a label is created at the current position/selection) but omits side effects such as whether an empty text creates an unlabeled label, whether a label track is required, or what happens to the existing selection.

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 main sentence is front-loaded, short, and directly actionable. The Args block is somewhat redundant with the schema, but it is minimal and does not add meaningful verbosity.

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?

The tool is simple and the description covers the basic invocation. However, in a large sibling family of label-related tools, it does not disambiguate from label_add_at or label_add_batch, and it does not mention any effects on the current selection or label track.

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?

The description adds only a slight clarification by calling text 'Label text' and repeating the schema's default of empty. Schema coverage is 0%; the description should compensate more, but for a single free-form string parameter it does provide enough meaning for basic use.

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 clear verb-resource pair ('Add a label') and the precise scope ('at the current cursor position or selection'). It is unambiguous about what the tool does, though it does not explicitly name sibling tools such as label_add_at to differentiate them.

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 usage context is implied by the purpose: use this when adding a label at the current cursor or selection. However, there is no explicit guidance about when to prefer label_add_at, label_add_batch, or track_add_label, nor any exclusions.

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