get_assignment_analytics

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

The annotation readOnlyHint=true indicates the tool is read-only, and the description is consistent with that, describing a 'Get' operation. The description adds the context that the analytics are about 'student performance' on a specific assignment, which goes beyond the schema. However, it does not disclose details like whether it returns aggregate statistics or individual breakdowns, or if any special permissions are needed. Given the annotation covers the main behavioral trait (read-only), the description adds reasonable context without contradiction.

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 one concise sentence that efficiently communicates the purpose. It is front-loaded with the key verb and resource, and there is no wasted text. It accurately reflects the tool's function without fluff.

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 tool is relatively simple with two clear parameters and a read-only annotation, but the description could be more complete. It doesn't describe what the output looks like (though no output schema is provided) or any specifics about the analytics (e.g., metrics included). Given the complexity is low and the schema covers the inputs, a 3 is reasonable, but there is room to add more detail about the return value or typical use cases. Sibling tools like 'get_student_analytics' might overlap, so more clarity would help.

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% with clear descriptions for both parameters ('Canvas assignment ID' and 'Course code or Canvas ID'). The description adds minimal extra meaning beyond the schema, just implying that the parameters identify a specific assignment. Since the schema covers the parameters well, a baseline of 3 is appropriate. The description does not clarify the relationship between the parameters or any format specifics, but the schema already does.

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 clearly states the tool's purpose: retrieving detailed analytics about student performance for a specific assignment. The verb 'Get' with the specific resource 'assignment analytics' is clear, and it distinguishes from sibling tools like get_assignment_details, which likely focuses on assignment content rather than performance analytics. However, it could differentiate slightly more explicitly from 'get_student_analytics' or 'get_peer_review_completion_analytics' which might overlap in scope.

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 implies usage context (when you need performance analytics for an assignment) but does not explicitly mention when not to use it or alternatives. Sibling tools like 'list_submissions' or 'get_my_submission_status' might provide related info, but no explicit guidance is given. The description is minimal and does not clarify the distinction from other analytics tools, so usage guidance is implied rather than explicit.

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