commands_get_global

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

The description adds value beyond the read-only annotations by detailing the return shape and the nuance that `name` and `description` are raw while `untrusted_text` is a separately fenced copy. This helps the agent understand what data to expect and how to handle it. It does not cover error cases or rate limits, but the core behavioral context is present.

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 concise and well-structured with bolded 'Purpose' and 'Returns' labels. It conveys the essential information in two short sentences with no repetitive or extraneous content.

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 simple fetch-by-ID operation, the description is fully complete: it states what the tool does, lists the return fields, and the schema covers the required parameters. Annotations cover the safety profile (read-only, idempotent, non-destructive). No critical information is missing.

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 100% for both parameters (command_id and application_id), so the schema already documents their meanings. The tool description does not add any additional semantic detail about these parameters, so the baseline of 3 applies.

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 verb ('Fetch'), the resource ('one global application command'), and the identifier ('by id'). This distinguishes it from sibling tools like commands_get_guild (which retrieves a guild command) and commands_list_global (which lists all global commands).

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 clear context on when to use this tool: to fetch a single global command by its ID. It does not explicitly state exclusions or alternatives (e.g., 'for guild commands use commands_get_guild'), but the scope is unambiguous and the name reinforces the distinction.

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