Link Gear to Activity

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

Annotations already declare destructiveHint: true and openWorldHint: true, so the safety profile is known. The description adds the tip about finding the gear UUID, which is helpful context, but it does not disclose any additional behavioral traits such as overwriting existing gear links or side effects. With annotations covering the destructive aspect, the description meets a baseline but adds limited extra value.

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 extremely concise: two sentences that immediately state the purpose and add a key practical detail. There is no redundant or extraneous information, and the structure is front-loaded with the action.

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 tool with two well-documented parameters and no output schema, the description covers the essential usage. It could theoretically mention that linking might replace existing gear assignments, but given the annotations already indicate destructiveness and the operation is straightforward, the description is sufficiently complete for an agent to proceed.

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%, as both gearUUID and activityId are fully described in the schema. The tool description's note about the gear UUID being in the URL is already present in the schema's parameter description, so it adds no new meaning. Per the guidelines, a baseline of 3 applies when schema coverage is high, which is the case here.

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 clearly states the action: 'Link a piece of gear to an activity.' It uses a specific verb and resource, and the context of gear and activity distinguishes it from sibling tools like remove_gear_from_activity. The additional note about needing the gear UUID adds practical context without confusing the purpose.

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 when to use this tool (to associate gear with an activity) but does not explicitly mention alternatives or when not to use it. It provides no comparison with related tools like remove_gear_from_activity or get_gear_activities, nor does it state prerequisites beyond the UUID. This is adequate but lacks explicit guidance.

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