Like or unlike a gist

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

The description adds meaningful behavioral context beyond the annotations by explaining the idempotency mechanism: it reads the current state first and only toggles when it differs, so repeated identical calls do not undo the action. It also discloses the required user:write scope, addressing authentication needs.

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 tightly written sentences front-load the purpose and then provide the two most critical behavioral details: idempotency and authentication. No filler or redundant repetition of schema contents.

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 boolean toggle tool, the description covers the operation, idempotent behavior, and required scope. The output schema exists for return values, and the annotations cover mutability and destructiveness, so nothing essential 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 coverage is 100%, so the baseline is 3. The description's idempotency explanation enriches the semantics of the "liked" boolean parameter, clarifying how repeated calls with the same value behave. This goes beyond the schema's simple 'true to like, false to remove' description.

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 opens with "Like or unlike a gist," a specific verb and resource that clearly states the operation. It distinguishes itself from siblings like check_gist_like by signaling a mutation rather than a read, and from update_gist by targeting like state specifically.

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 purpose makes the primary use case obvious: to set or remove a like on a gist. However, it does not explicitly mention alternatives such as check_gist_like for reading the current state, nor does it state when not to use this tool. This is clear context without exclusions.

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