get_commits

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

No annotations are provided, so the description carries the full burden. It mentions that commits are 'recorded by the post-commit hook', which gives some transparency about how the data is collected, but it doesn't disclose behavior like what 'recent' means in time range (the default is 7 days but that's in schema), whether it sorts, or if it includes any other details. The description doesn't state any side effects (though likely read-only) or additional context. Given no annotations, more behavioral disclosure is expected.

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 a single concise sentence, front-loaded with the action and resource. It mentions the recording mechanism, which adds useful context without redundancy. It's efficient and to the point.

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 single-parameter read tool, the description is fairly minimal. It doesn't explain what the response looks like (though no output schema exists), nor does it clarify the time window beyond the parameter. It doesn't mention any prerequisites or side effects. Given the simplicity, it's adequate but could include a bit more context on the 'recent' definition or that it returns commit details.

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 only parameter is 'days' with a default and min/max in the schema. The description does not explicitly explain 'days' beyond the implied 'recent', but since the parameter has a clear name and the schema provides constraints, the description doesn't need to add much. However, schema description coverage is 0%, so the description should compensate by explaining what 'days' represents, but it doesn't explicitly. Given there is only one parameter and it's self-explanatory, the description adds little value beyond the schema. Baseline 3 is appropriate because the schema is not documented but the parameter name is clear.

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 states the verb 'Get', the resource 'git commits', and the temporal scope 'recent', which is a clear purpose. It also hints at a recording mechanism ('recorded by the post-commit hook'), which adds specificity. However, it doesn't explicitly distinguish from any sibling tool, but none of the siblings are similar (get_work_log, get_weekly_summary are different resources). So slight deduction for no explicit differentiation, but the purpose is clear.

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 no guidance on when to use this tool versus alternatives. It doesn't mention any context, such as 'use this for commit history', nor any exclusions. Since there is no explicit alternative, the tool could have stated that it specifically returns commits recorded by a hook, implying it's used when such data is needed, but that's only implied. No when-not or alternative guidance is provided.

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