docs: improve tools reference readability

[aworki]

Summary

• remove embedded parameter lists from the tools reference table so the tool-name column can stay readable
• add a note directing readers to each linked tool page for full parameters and usage details
• add a regression test that keeps parameter lists out of the table section

Testing

• ./node_modules/.bin/vitest run --config ./scripts/tests/vitest.config.ts
• ./node_modules/.bin/prettier --check docs/reference/tools.md scripts/tests/tools-reference-doc.test.ts

Fixes #21504

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the clarity and conciseness of the tools reference documentation. By streamlining the main table to focus on high-level descriptions and guiding users to dedicated pages for detailed parameters, the documentation becomes easier to navigate and digest. A new test ensures this improved structure is maintained going forward.

Highlights

• Documentation Readability: Improved the readability of the tools reference table by removing embedded parameter lists from the descriptions.
• User Guidance: Added a note to the tools reference table, directing readers to individual tool pages for comprehensive parameter and usage details.
• Regression Testing: Introduced a new regression test to ensure that parameter lists are not re-introduced into the main tools reference table descriptions.

Changelog

• docs/reference/tools.md
  • Removed detailed parameter lists from the 'Description' column of the tools table.
  • Added a new introductory sentence to the 'Available tools' section, advising users to follow links for full parameter details.
• scripts/tests/tools-reference-doc.test.ts
  • Added a new test file to validate that the 'Available tools' section in tools.md does not contain embedded parameter lists.

Activity

• No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request improves the readability of the tools reference documentation by removing parameter lists from the main table and adding a regression test to enforce this. The documentation change is clear and effective. The new test is a great addition for maintainability, but its implementation could be more robust to avoid silent failures. I've added a suggestion to improve the test's reliability.

[gemini-code-assist]

The current implementation of getAvailableToolsSection is not robust. If the ## Available tools heading is missing or renamed, the test will silently pass because the destructuring assignment with a default value (= '') will hide the error. This can lead to a false sense of security. To make the test more reliable, it should explicitly check that the document sections are found and throw an error if they are not. This ensures the test fails loudly if the document structure changes unexpectedly.

async function getAvailableToolsSection(): Promise<string> {
  const toolsReference = await readFile(toolsReferencePath, 'utf8');
  const [, afterAvailableTools] = toolsReference.split('## Available tools');
  if (afterAvailableTools === undefined) {
    throw new Error('Could not find "## Available tools" heading in tools.md');
  }
  const [section] = afterAvailableTools.split('## Under the hood');
  if (section === undefined) {
    throw new Error('Could not find "## Under the hood" heading in tools.md');
  }
  return section;
}

[aworki]

Hi maintainers — gentle consolidated follow-up for my open PRs in this repo (#21550 and #21241) to keep notifications low.\n\nCurrent status from my side:\n- #21550: docs-pr-check is still pending\n- #21241: CI appears green, currently waiting for maintainer review\n\nIf there is any extra contributor-side step needed (for docs-pr-check queue/approval or preferred next action), I can do it immediately. Thanks!

[priyanshuKumar56]

/assign

[g-samroberts]

Hi, this issue is already fixed by a PR submitted by a contributor assigned to issue. Before creating future PRs, please make sure the issue is labeled as help-wanted and unassigned, and assign to yourself with the /assign comment. Thanks!