github_create_issue

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

Annotations provide readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=true. The description doesn't contradict these but also doesn't explain them—e.g., it doesn't say that creating an issue modifies external state, that the GitHub API may normalize or reject certain fields, or what happens to unknown fields in the open-world setting. With annotations covering safety profile, credit is given for not contradicting them, but no extra behavioral context is added.

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 short and the core purpose is front-loaded, but the parameter list is just a schema rephrasing with no added value. Some lines are empty stubs ('title (required):' has no explanation). It earns a 3 for being brief and organized, but the parameter lines are not maximally informative.

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 write tool with 11 parameters, 0% schema coverage, and no usage guidance, the description is incomplete. It doesn't explain the nontrivial parameters (idempotency_key, effect, approval_ref, project_ref), doesn't note that all parameters are optional at the schema level, and doesn't describe the output schema even though one exists. An agent would struggle to call this correctly in non-trivial cases.

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 by explaining the parameters. It lists parameter names with terse one-liners, but many are opaque: 'project_ref: Exact project correlation reference', 'idempotency_key: Stable business-action identity', 'effect: Claimed read or write effect; Spring verifies it'. No format, example, or relationship between project_id/project_ref/connector_account_ref is given. The agent cannot know how to construct these values.

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 'Create an issue in a repo' is a clear verb+resource statement. It distinguishes this from related siblings like github_create_issue_comment, github_create_pull_request, and github_update_issue, though it could be more explicit about not being those tools.

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 provides no guidance on when to use this tool versus alternatives. Among many GitHub siblings (github_create_issue_comment, github_update_issue, github_create_pull_request), an agent gets no hint about when issue creation is appropriate or what prerequisites exist (e.g., repo must already exist).

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