list_project_items

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals that for user-owned projects it falls back to an unofficial page-scraping method that 'could break if GitHub changes its page structure'—a critical risk that an agent must know. It does not mention pagination or return format, but the core behavioral trait is well exposed.

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 consists of two sentences: the first states the core purpose and result content, and the second provides the essential implementation caveat. Every sentence earns its place with no redundant or filler phrasing.

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 no output schema and no annotations, the description must convey enough context for safe invocation. It covers the purpose, result contents, and a major behavioral difference between owner types. Gaps include pagination behavior and error conditions for private/non-existent projects, but for a listing tool with fully documented parameters this is acceptably complete.

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 already covers all 3 parameters at 100%, so baseline is 3. The description adds meaning to the 'ownerType' parameter by explaining that 'user' triggers the unofficial fallback while 'org' uses the official REST API, which is not obvious from the schema alone. This extra context helps the agent predict behavior per owner type.

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 the specific verb 'List' with a clear resource: 'all items (issues/PRs/draft issues) in a public GitHub Projects (v2) board'. It enumerates the output contents (status, custom field values, metadata), which distinguishes it from siblings like get_project_item (single item) and get_project_fields (schema).

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 clearly implies this is the tool for listing all items in a public project board, and it provides contextual guidance on the behavioral split between org-owned and user-owned projects. However, it does not explicitly state 'when not to use this' or name alternative tools, though siblings are obvious.

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