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

Annotations are all false, providing no inherent behavioral hints. The description adds useful context: 'writes a local .axint/session workflow freshness stamp; edits no app source and uses no network.' This discloses side effects and safety boundaries. It could go further on failure modes or exact file format, but given the absence of annotation guidance, this is strong. No contradiction with annotations.

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?

Three sentences: purpose, usage, and inputs/effects. Front-loaded with the primary action, each sentence carries distinct value. No filler or redundancy. The structure makes it easy to scan.

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 description covers purpose, usage, preconditions, side effects, and safety boundaries (no source edits, no network). An output schema exists, so return format is covered elsewhere. The only gap is the parameter name inconsistency ('allowNoSession' vs 'requireSession'), which causes minor ambiguity. Overall, it is near-complete for a complex 23-parameter tool.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds high-level semantics for a few key params ('stage selects the gate; sessionToken proves continuity; allowNoSession is an explicit escape hatch'), but it misnames the parameter: schema has 'requireSession', not 'allowNoSession'. This mismatch could mislead an agent. It also doesn't map the full set of 23 params, though that is unnecessary given schema coverage.

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 a specific verb+resource: 'Agent workflow gate that records a local freshness stamp.' It clearly states the tool's role as a workflow gate, and explicitly distinguishes it from siblings: 'use status for version checks and run for build/test proof.' This differentiates it from tools like axint.status and axint.run.

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?

Usage guidance is explicit: 'Use: use at stage gates to prove workflow coverage; use status for version checks and run for build/test proof.' This states when to use this tool and when to prefer alternates. It also specifies the session token requirement and the escape hatch via requireSession=false, setting clear preconditions.

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