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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description adds genuinely useful extra context beyond those: 'Works without a token' (auth behavior) and that the reference is returned 'one part at a time' (scope of a single call).

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 content mostly earns its place, but the prose is dense and run-on ('With part reference, one part of the reference: ... or one operation by name'), making it harder to scan than the parallel structure of the underlying enum. Front-loading the primer's purpose is good.

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?

There is no output schema, and the description effectively describes what each part returns, which is what an agent needs for a documentation-retrieval tool. A token-requirement statement and the part-selection mechanics are all present; only return-format granularity is left implicit.

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 coverage is 100%, so the baseline is 3, but the description goes further by explaining the conditional interaction between parameters: part=reference uses section ('section refusals when a call is refused...') or operation by name. That relationship adds meaning beyond the per-field schema text.

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 identifies the tool as the onboarding primer/reference resource and enumerates what each part contains (primer, reference, capabilities, reviewer_rules). It clearly distinguishes itself from the sibling schellingaf_whoami, though the actual retrieval verb is only implied rather than stated.

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?

It explicitly routes the agent: 'Connected already? Start with schellingaf_whoami instead,' and then specifies exactly when to use each part value (reference for refusal codes, capabilities for limits/word lists, reviewer_rules for oracle-space rules). This is explicit when-to-use plus an alternative.

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