sync_course

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

No annotations are provided, so the description carries the burden of behavior disclosure. It does disclose a meaningful side effect: prefetching and indexing into a local SQLite database. But it doesn't describe whether force_refresh is needed, whether existing data os overwritten, whether this is idempotent, or what the return shape indicates.

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?

Two sentences, no filler, core action and benefit both meaningfully expressed. It earns its length completely and remains easy to digest.

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 provides context for the operation, but with no annotations, no parameter guidance, and no explicitystatement of what force_refresh controls, the tool is not fully documented for correct invocation. In partial output schema exists so return details are not unneeded, but usage and refresh behavior remain unfinished.

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%, so the description must explain the parameters, but it only says 'all lesson transcripts and syllabus for a course' which reasonably implies course_slug. It fails to mention force_refresh entirely, leaving the sole optional parameter undocumented by both schema and description.

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 pair: 'Pre-fetch and index all lesson transcripts and syllabus for a course'. It clearly indicates the tool's scope and its local SQLite target, distinguishing it from sibling retrieval tools like get_lesson_transcript and search_course_content.

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?

Implied usage — the tool prepares course content for offline search and note-taking, so an agent can infer when to call it before other content access. However, it never names alternatives, states when not to use it, or contrasts with search_course_content/get_lesson_transcript.

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