Skip to content

feat(git): say git_log is newest-first and its timestamp filters are optional - #5626

Open
cliffhall wants to merge 1 commit into
v2/mainfrom
v2/feat/5552-git-log-description
Open

cliffhall wants to merge 1 commit into
v2/mainfrom
v2/feat/5552-git-log-description

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5552

Description

git_log's description was Shows the commit logs. It did not say that results come newest first, or that start_timestamp / end_timestamp can be left out, and a small model asked for the most recent commit filtered itself to an empty window (start_timestamp="now", end_timestamp="now"), got a bare Commit history: and concluded the repository had no commits.

This PR changes what the model reads, in the two places it reads it:

  • The tool description now says results are newest first, that the latest commits need only repo_path (and optionally max_count), and that the two timestamps are optional filters to omit unless a period is asked for.
  • Each timestamp's description now opens with Optional: and says what omitting it means (no lower / upper bound).
  • The empty result under a filter now names the cause and the way out: Commit history:\nNo commits match the given start_timestamp/end_timestamp. Omit both to see the latest commits. The Commit history: first line is kept, and a call with no timestamp is unchanged.

The tool's name, parameters, schema types, defaults and annotations are unchanged.

Server Details

  • Server: git (mcp-server-git)
  • Changes to: the git_log tool's description, its two timestamp parameter descriptions, and its result text when a timestamp filter matches no commits; the README's git_log entry.

Motivation and Context

#5552, with the reporter's measurements (qwen3:4b-instruct, deterministic repository, answers checked in code): the "most recent commit" question went from 1/6 to 3/3 with a description of this shape, and they asked for the empty-result hint to cover a model that still adds filters.

How Has This Been Tested?

A fixture repository with three commits (10 Jan, 10 Feb, 10 Mar 2026). Inspector CLI 2.9.0, server over stdio, every command run with --protocol-era legacy (2025-11-25) and --protocol-era modern (2026-07-28); the output was the same in both eras, before and after.

npx -y @modelcontextprotocol/inspector@2.9.0 --cli \
  uv --directory src/git run mcp-server-git --repository "$REPO" -- \
  --method tools/list --protocol-era <era> --format json

git_log as served, base 7f383a8e:

{"description":"Shows the commit logs","params":{"start_timestamp":"Start timestamp for filtering commits. Accepts: ISO 8601 format …","end_timestamp":"End timestamp for filtering commits. Accepts: ISO 8601 format …"}}

This branch:

{"description":"Shows the commit log, newest commit first. For the latest commits, pass only repo_path (and optionally max_count). start_timestamp and end_timestamp are optional filters for a date range: omit them unless a specific period is asked for, because a range that holds no commits returns none.","params":{"start_timestamp":"Optional: only show commits at or after this time. Omit for no lower bound. Accepts: ISO 8601 format …","end_timestamp":"Optional: only show commits at or before this time. Omit for no upper bound. Accepts: ISO 8601 format …"}}

The call from the issue, --method tools/call --tool-name git_log --tool-args-json '{"repo_path":"…","max_count":1,"start_timestamp":"now","end_timestamp":"now"}':

Result text
Base Commit history:\n
Branch Commit history:\nNo commits match the given start_timestamp/end_timestamp. Omit both to see the latest commits.

Unchanged on the branch (identical to the base, both eras):

  • {"repo_path":"…","max_count":2} returns the 10 Mar commit, then the 10 Feb commit (newest first).
  • {"repo_path":"…","start_timestamp":"2026-02-01","end_timestamp":"2026-02-28"} returns the 10 Feb commit only, with no hint.

LLM client: Claude Code 2.1.327, headless (claude -p --mcp-config … --strict-mcp-config --allowedTools mcp__git__git_log), against this branch's build. It has no era switch and does not print the negotiated version, so the era was not selected. Prompt: "who made the most recent commit and what is its message? Then call git_log with start_timestamp and end_timestamp both set to 'now' and quote exactly what the tool returned. List the exact arguments you passed." It called git_log with {"repo_path": …, "max_count": 1} (no timestamps) and answered with the 10 Mar commit; the second call returned the hint text above verbatim.

Not reproduced here: the reporter's small-model measurement (qwen3:4b-instruct through their AgentGrade harness). Their numbers for a description of this shape are in #5552.

Tests (src/git/tests/test_protocol.py, through an MCP client): the tools/list wire snapshot carries the new text; a new test asserts the description states the order and that both timestamps are optional and not required; a new test asserts an empty window returns the hint while the same call without filters returns the newest commit; the existing filter test now expects the hint for its two empty ranges. npm run local:gate exits 0; its interface diff shows exactly the three description changes.

Breaking Changes

None. No client configuration changes. A client that matched the exact text Commit history:\n for an empty filtered result now sees a second line after it.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation
  • My changes follow MCP security best practices
  • I have updated the server's README accordingly
  • I have added a changeset (not applicable: a Python server; no TypeScript package changes)
  • I have tested this with an LLM client
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling (not applicable: no new failure path; the empty result is a normal result, not an error)
  • I have documented all environment variables and configuration options (not applicable: none added)

Additional context

🤖 Generated with Claude Code

…optional

git_log's description was "Shows the commit logs". A small model asked for
the most recent commit passed start_timestamp="now" and end_timestamp="now",
got a bare "Commit history:" and concluded the repository had no commits
(#5552).

The description now says results are newest first and that both timestamps
are optional filters to leave out unless a period is asked for, and each
timestamp's description says what omitting it means. When a timestamp filter
matches no commits, the result names the filter as the cause and says to
omit both, instead of an empty history. The tool's name, parameters and
schema types are unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 7d24637

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@cliffhall
cliffhall requested a balanced review from Copilot November 18, 2026 19:14
@github-actions

Copy link
Copy Markdown
Contributor

git: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 7fb7be13710f (Merge 7d24637 into 7f383a8)

Diffed because it was named (--server).

⚠️ Interface changes detected in 1 part(s) of the interface. Review them below to confirm they are intended.

Tools Prompts Resources Resource templates
Base 14 2 0 0
Head 14 2 0 0

tools

--- base/tools.json
+++ target/tools.json

- tools[git_log].description: "Shows the commit logs"
+ tools[git_log].description: "Shows the commit log, newest commit first. For the latest commits, pass only repo_path (and optional..."
- tools[git_log].inputSchema.properties.end_timestamp.description: "End timestamp for filtering commits. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relativ..."
+ tools[git_log].inputSchema.properties.end_timestamp.description: "Optional: only show commits at or before this time. Omit for no upper bound. Accepts: ISO 8601 forma..."
- tools[git_log].inputSchema.properties.start_timestamp.description: "Start timestamp for filtering commits. Accepts: ISO 8601 format (e.g., '2024-01-15T14:30:25'), relat..."
+ tools[git_log].inputSchema.properties.start_timestamp.description: "Optional: only show commits at or after this time. Omit for no lower bound. Accepts: ISO 8601 format..."

Updated by this run for 7d246370e0b36482784a19d7aa82929bf210ce97.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the git_log guidance and filtered-empty response changes.

No open issues 🎉

What changed in this PR

This PR clarifies the Git reference server’s git_log guidance so models can request recent commits without unnecessary timestamp filters, addressing #5552 without changing the input schema.

Changes:

  • Describes newest-first ordering and makes timestamp-filter optionality explicit.
  • Adds a recovery hint when timestamp filters return no commits, leaving unfiltered responses unchanged.
  • Updates the README, protocol tests, and tool metadata snapshot to reflect the behavior.
File Description
src/​git/​tests/​test_protocol.py Tests the empty-filter hint and model-visible ordering and optionality guidance.
src/​git/​tests/​snapshots/​list_tools.json Updates the tool and timestamp descriptions in the wire snapshot.
src/​git/​src/​mcp_server_git/​server.py Clarifies descriptions and adds the filtered-empty response hint.
src/​git/​README.md Documents ordering, optional filters, and the returned text.

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: clean (no findings, no suppressed comments). The review loop ends here on the first clean round; nothing was pushed after the review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

git: git_log description doesn't say results are newest-first or that timestamp filters are optional; small models filter to an empty window

2 participants