get_graph_stats

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal an important behavior: the freshness analysis uses git diff against the commit when the graph was last analyzed, which implies a potentially expensive operation. It also lists what statistics are returned. However, it does not mention whether the tool is read-only, potential side effects, or any computational cost or rate limits.

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 well-structured with clear Args and Returns sections, and it front-loads the core purpose in the first sentence. It is a bit verbose with the freshness analysis explanation, but every sentence adds value and there is no redundant fluff.

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?

The tool is relatively simple with one optional parameter and an output schema exists, so the description covers the basic return contents. However, it lacks guidance on how this tool relates to siblings (especially get_graph_metadata) and does not address potential costs or operational nuances of the git diff-based freshness check. This leaves some context gaps for an agent deciding whether to invoke it.

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 input schema provides no description for the 'project' parameter (0% coverage), so the description's parameter explanation is essential. The description clearly explains that 'project' is a project name and that leaving it empty is valid when only one project is loaded, which adds meaningful semantics beyond the schema's bare type information.

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 tool's function with a specific verb ('Get') and resource ('project's knowledge graph'), and adds scope details (comprehensive statistics, freshness analysis). However, it does not distinguish itself from the sibling tool 'get_graph_metadata', which likely has overlapping functionality, so it falls short of full differentiation.

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 gives no explicit guidance on when to use this tool versus alternatives like get_graph_metadata or query_nodes. It implies usage for statistics gathering but provides no exclusions, prerequisites, or comparative context. This leaves the agent without clear selection criteria.

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