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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral details: it reports Symvanta's indexed state rather than local git, explains that currentRemoteSha can be null without credentials, and discloses that the active ref pin is echoed. These are exactly the kind of non-obvious behaviors an agent needs to interpret results correctly.

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 three sentences with no filler. It front-loads the return values and purpose, then adds essential caveats and additional output context. Every sentence earns its place and even the null behavior is covered compactly.

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 simple read-only freshness check with no output schema, the description covers the returned fields, a key null condition, and the distinction between Symvanta state and local git. It could additionally explain when lastIndexedSha/lastIndexedAt might be null or how the active ref pin is determined, but the essentials for correctly using and interpreting the tool are present.

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 already describes all three parameters thoroughly, including projectId, repository, and the feedback object, with 100% coverage. The description does not need to repeat parameter details. It adds no parameter-level meaning, but the schema carries the full burden, so the baseline score of 3 is appropriate.

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 opens with the exact resource and fields returned ('lastIndexedSha, lastIndexedAt, and the current remote HEAD sha') and immediately states the purpose: 'detect index drift from remote.' It also differentiates the tool from local-git operations by saying 'Reports what Symvanta knows, not local git,' which clearly separates it from sibling tools focused on git or indexing.

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 a clear use case: detect whether the indexed repository has drifted from the remote. It also provides useful context about the meaning of 'currentRemoteSha' when no GitHub credential is configured. However, it does not explicitly name alternative tools or state when not to use this tool, such as when checking local git state.

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