Assign a report to myself

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

Goes well beyond the annotations: it says any current assignee is replaced (confirming the destructive profile), that the researcher is not notified (a non-obvious side effect), and that approval happens on the website first (an auth/workflow precondition). It also implies the caller must hold the triager role on an opted-in org.

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?

Compact and front-loaded with the action and its target; every sentence carries information (scope, replacement behavior, alternative path, notification behavior, approval flow). The phrasing is slightly tangled ('belongs to to the signed-in user'), which costs a point but not comprehension.

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?

Covers the qualifying scope, the side effect on existing assignees, the notification outcome, and the external approval prerequisite. Return values need not be described since an output schema exists.

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 single parameter is fully documented in the schema, so the schema does the heavy lifting. The description nonetheless adds a validity constraint on reportId by restricting it to reports from an opted-in organisation the user belongs to, which is not in the schema, plus the schema points to list_org_reports for sourcing ids.

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?

States a specific verb (assign) and resource (a report) plus the exact target (the signed-in user, as the organisation's triager). It also scopes which reports qualify (opted-in organisation the user belongs to), so no sibling tool could be confused with it.

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?

Explicitly routes the out-of-scope case elsewhere: 'Assigning to someone else is done on the BugSecure website.' It also states the prerequisite that the user approves on BugSecure first, so the agent knows the call only succeeds in that context.

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