list_gists

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

With no annotations provided, the description does a good job of disclosing the read-only nature via 'List' and the return shape (array of base-gist objects with specified fields). It also clarifies what is not included (full file content) and mentions pagination. It could add details about authentication requirements or rate limits, but these are common to GitHub API tools.

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, with three sentences that front-load the main purpose, then provide return details and pagination, and finally an alternative. Every sentence adds value, and the docs link is useful without being intrusive.

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 list endpoint with no output schema, the description adequately explains the return type, fields, and limits (no full content). It covers pagination and directs to get_gist for content. Missing details like the 'since' parameter in the description (though in schema) and sort order are minor gaps, but overall the description is sufficiently 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 covers only 'since' with a description (33% coverage), while page and per_page lack descriptions. The description mentions 'Paginate with page and per_page' but does not explain their exact semantics or constraints; however, the schema provides defaults and min/max. The description partially compensates by connecting pagination to the tool's overall list behavior, but not fully.

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 the resource 'gists' and scopes it to 'the authenticated user,' clearly defining the tool's primary function. It also distinguishes this from sibling get_gist by noting that full file content requires calling get_gist with the gist's id.

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 explicit usage context by mentioning pagination with page and per_page, and explicitly directs users to get_gist for full file content, serving as an alternative. This gives clear guidance on when to use this tool versus its primary sibling.

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