github_disconnect

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does not state what happens after disconnecting (are credentials deleted? is the session token revoked? does it affect github_status?). For a state-changing operation on a connection, the side effects and reversibility are entirely undisclosed.

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 appropriately brief - a one-line purpose statement plus a compact parameter docstring. No wasted words or redundant content. It's front-loaded with the core purpose before the parameter detail.

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?

Despite having an output schema and simple parameter set, this is a state-changing tool (disconnect) paired with its counterpart (github_connect). The description doesn't explain return values, side effects on credentials, session lifecycle, or error cases. Given the tool has 70+ siblings and relates to authentication state, more guidance is warranted.

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 has 1 parameter with 0% description coverage, meaning the description must compensate. The description does mention the session_name parameter inline ('Name of the session to disconnect'), which adds meaning beyond the schema. However, this is minimal value since the schema already provides the parameter name and a default value. The description adds only the brief semantic of what the parameter selects.

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+resource ('Disconnect a GitHub session') which makes the basic purpose clear. However, it doesn't distinguish this from github_connect or github_status in terms of what 'disconnect' means (e.g., does it remove credentials, end auth, revoke the token?). The purpose is understandable but lacks specificity about what disconnecting actually does.

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?

There is no guidance on when to use this tool versus alternatives like github_connect or github_save_credentials. The description doesn't clarify whether this is needed before reconnecting, whether it invalidates stored credentials, or any prerequisites. For a semantic opposite of github_connect, it should clarify the relationship.

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