set_project_pin

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

The description only states that the tool modifies project state by pinning/blocking a pack, with no additional behavioral details. It does not disclose whether pins replace existing pins, how block accumulation works, or any permission requirements. With no annotations, this sparse disclosure is insufficient for a mutation tool.

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 one short sentence with no wasted words, front-loading the action and resource. It is concise but at the expense of explanatory depth, making it somewhat under-specified for the tool's complexity.

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 state-changing tool with optional parameters and no annotations or output schema, the description is far too sparse. It omits information about how pin and block parameters interact, side effects, and what happens on success or failure, making it inadequate for reliable invocation.

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 schema provides no descriptions (0% coverage), and the description adds no parameter-level meaning. It mentions 'specific pack' and 'project' but does not map to pinned_pack_id versus blocked_pack_ids, leaving the agent unable to infer parameter semantics.

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 (pin/block) and the resource (a specific pack in a project), which distinguishes it from read/search siblings like list_packs and find_asset. However, it does not explicitly separate what it means to pin versus block, leaving slight ambiguity about the two behaviors.

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?

No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, common scenarios, or context for when pinning/blocking is appropriate. The agent cannot determine when to select this tool over suggest_packs or list_packs.

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