get_analytics_learning_activity

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

The description goes well beyond the readOnlyHint and destructiveHint annotations by disclosing that auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx responses surface as tool errors with specific status meanings. This gives the agent rich context about rate limits, error handling, and operational safety.

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 description is structured into clear sections — purpose, Behavior, Returns, Use when — with front-loaded read-only status and endpoint path. Each sentence carries useful information, and there is no redundant filler despite the moderate length.

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 comprehensively covers behavioral, auth, throttling, and error semantics, which is strong for a tool with only two simple parameters. However, since there is no output schema, the return value description ('LearnWorlds JSON response body') is vague and does not explain what analytics fields will be present; a bit more detail about the payload shape would make it fully complete.

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 100%, so the schema already documents both parameters ('Course title Id' and 'Learning activity id'). The description merely repeats the concept of 'course id and learning activity id' without adding format constraints, examples, or clarification of the ambiguous 'Course title Id' label, so it adds no real value beyond the 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?

The description states a specific verb and resource: 'Get analytics for a learning activity' and clarifies the scope by specifying the course id and learning activity id. It also distinguishes itself from related reporting tools like get_analytics_course and get_user_progress, so an agent can identify what this tool does.

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 description gives explicit guidance: 'safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It names related reporting tools as alternatives, but does not explain when to prefer this tool over get_analytics_course, get_user_progress, or get_user_progress_per_course, so the selection criteria between these siblings remains implicit.

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