enroll

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

With no annotations, the description carries the full behavioral burden and does so substantially: it discloses that recording a keyed route creates an enrollment request, that Scout tests the key on the sample before marking 'enrolled', and the key-handling constraint ('keys are never passed here: they go in the keys file or SCOUT_KEY_<NAME> env vars'). It still omits permissions required, reversibility, and what a call returns, which keeps it from a 5.

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 text is dense but nearly waste-free, with each action line earning its place and key-handling rules placed last as a constraint. Structure is poor, though: it is a run-on block with slash- and pipe-delimited fragments and no front-loaded summary, making it harder to scan than its length warrants.

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 5-parameter, no-annotation, no-output-schema workflow tool, the description covers the action modes and the info payload adequately but leaves host/note/include_all undocumented and gives no return-value or state-transition details. It is usable for the common path but incomplete for an agent needing to call it precisely in every mode.

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 0% across 5 parameters, so the description must compensate and it does so well for the two hardest inputs: the full action= vocabulary (which supplies the missing enum) and the nested info object's fields (route types, auth kinds, sample, cost). The host, note, and include_all parameters, however, are left completely unexplained in both schema and description, so compensation is only partial.

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 states a specific resource ('official routes and the enrollments they need') and enumerates distinct operations via action= list/request/applied/done/decline, so an agent can tell it manages the enrollment workflow rather than generic site data. It does not name any sibling tool, however, and the referent 'Scout' is undefined, leaving some ambiguity about the boundary versus tools like site_map or scout.

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 action= vocabulary implicitly conveys the workflow states (open request → applied → done/decline), which is useful triage context. But there is no explicit statement of when to choose enroll over its siblings, no preconditions, and no when-not-to-use condition; the agent must infer usage from the mode names.

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