list_project_fields

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the useful constraint that item field values are not returned, which is genuine behavioral context beyond the annotations. However, it doesn't detail pagination behavior, rate limits, or what happens for empty projects. With annotations covering the read-only nature, a mid score is appropriate.

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 sentences, both informative and free of filler. The exclusion clause is front-loaded and valuable. Could arguably be shorter, but every sentence earns its place; there's no wasted text.

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 a list operation and modest complexity, with annotations declaring read-only safety. The core purpose is clear and the exclusion note is helpful. However, with no output schema and zero parameter semantics coverage, an agent needs more guidance on what field metadata looks like and how the three related parameters interact. It's adequate but not complete for a 5-parameter tool.

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%, and the description adds no parameter explanations. The 5 parameters (account, owner, projectId, limit, hostname) have no semantic guidance beyond regex patterns in the schema. The description mentions 'project' but doesn't clarify the distinct roles of account vs owner vs projectId, or what limit controls (number of fields vs options). With zero coverage and 5 params, the description should compensate but does nothing.

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 (list), the resource (field metadata and selectable option IDs), and the scope (GitHub Projects v2 project). It also explicitly notes what is NOT returned ('Item field values are not returned'), which distinguishes it from item-oriented siblings like list_project_items and set_project_item_field and add_project_item.

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 indicates what the tool lists but gives no guidance on when to use it versus alternatives. It doesn't mention prerequisites (auth, account ownership), nor does it contrast with list_project_items to clarify when each is appropriate. The 'Item field values are not returned' note subtly implies a distinction but doesn't explain what to use when you need field values.

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