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

Beyond the readOnlyHint/destructiveHint annotations, it discloses non-obvious behavior: topic_masteries is conditionally omitted when detail was not loaded, empty means loaded-but-no-practised-topics, and mastery appears only on projects, not followed_courses. It also states the read-only contract and the source-of-truth model (Infinite Practice attempts write; Agent OS only reads), which an agent cannot infer from 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?

Front-loads the purpose and payload before getting into conditional field semantics, and most sentences carry operational weight. It is dense at roughly 150 words with some tangential material (the ACE/mobile/write-path aside), but nothing is outright filler for a tool with this much conditional output.

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?

Although an output schema exists, the description supplies the interpretive layer the schema can't: the omitted-vs-empty distinction for topic_masteries and where mastery flags live. Combined with the read-only statement and scope semantics, an agent has everything needed to call and interpret it correctly.

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 baseline is 3, but the description adds real meaning: it explains that course_id/project_id narrow which course is 'in scope' and therefore whether topic_masteries is populated. That causal link between the scoping parameters and the conditional output field goes beyond the schema's terse 'Narrow context to...' 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?

States a specific verb and resource ('Return the unified Agent OS context manifest for the authenticated user') and enumerates the payload: profile, followed courses, project metadata, recent activity. It also draws a boundary against siblings by naming get-course-mastery as the tool for practised-topic detail, so the agent can separate them without opening either schema.

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 an explicit alternative and the condition selecting it: 'Use get-course-mastery(course_id) for the practised-topic list when context omitted detail.' It also explains when topic detail is in scope (project_id, sole remaining project, or shared course_id). What's missing is any routing guidance versus get-project-state or agent-os-session, so it stops short of full when/when-not coverage.

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