Get GOL schema

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

With no annotations, the description does real work: it discloses the output is raw text not rendered markdown, that content is generated by `specmgr schema` and kept current by a pre-commit hook/CI, and that a `$comment` version marker enables shape-change detection. It doesn't discuss permissions or caching, but read-only retrieval is implied and the freshness/source disclosure is well beyond typical.

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?

Front-loads what is returned before the usage guidance and the version-marker detail. It is a single dense paragraph and slightly overstuffed, but each clause (raw text vs markdown, source, freshness, $comment marker) carries distinct information.

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 zero-parameter read tool with an output schema, the description covers purpose, selection, format, provenance, and freshness, which is everything an agent needs before invoking it. Return-value detail can safely be deferred to the output schema.

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 tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to add. The description appropriately spends none of its space restating an empty schema.

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?

States a specific verb and resource ('Return the GOL domain's generated JSON Schema as raw text') and explicitly disambiguates from the markdown view and from get_gol_template. An agent can distinguish it from the many get_*_schema and get_*_template siblings without opening schemas.

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?

Gives concrete triggers ('constraint discovery, structural questions, or an unresolved validation error') and an explicit exclusion ('never as a mandatory pre-authoring fetch'), plus names the alternative for authoring. Nothing is left to inference.

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