clear_project_item_field

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

Annotations are present: readOnlyHint=false indicates mutation, idempotentHint=true indicates repeated clearing is safe, destructiveHint=false indicates the item itself isn't deleted. The description adds little beyond annotations—'Clear one supported field value' doesn't reveal what happens to the field (set to null vs default), whether the operation succeeds on already-empty fields, or what response is expected. With annotations present and consistent, this is acceptable but minimal.

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 a single, focused sentence with zero waste. It's appropriately sized for a relatively simple mutation tool. The main brevity concern is that while it's concise, it omits useful qualification about supported fields, but conciseness itself is well-executed.

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?

With 6 parameters, 0% schema coverage, 5 required parameters, no output schema, and no prose for any parameter, this description is substantially under-specified for the tool's complexity. It needs to explain the fieldId source, the account parameter role, and what 'supported field' means. The annotation set is minimal, and there's no guidance on how this tool integrates with list_project_fields or how it compares to set_project_item_field for clearing.

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 0%, so the description must compensate, but it doesn't explain any parameter semantics beyond what the schema patterns convey. The description doesn't clarify that fieldId must be obtained from list_project_fields, that account is the GitHub account/login scope, or how itemId and projectId relate. All 6 parameters are undocumented in prose, leaving the agent to infer semantic relationships from schema patterns alone.

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 uses a specific verb+object structure: 'Clear one supported field value on a GitHub Projects v2 item.' It clearly states the action (clear field value) and the resource (GitHub Projects v2 item). While it distinguishes from siblings like set_project_item_field, it doesn't explicitly name the alternative, and the phrase 'supported field' is slightly vague about which fields are supported.

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 want to clear/reset a field on a project item) but provides no explicit guidance on when to use this vs alternatives, no prerequisites (e.g., needing the fieldId from list_project_fields), and no exclusions about which fields are not supported. The 'supported field' qualifier hints there are restrictions but doesn't specify them.

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