list_submissions

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It merely lists output fields (user id, submitted_at, current score, attempt count) but says nothing about whether the operation is read-only, whether it returns all submissions for an assignment, if there is pagination, or if any side effects or permissions apply. This is a significant gap for a tool that likely reads data.

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 extremely concise, consisting of one short sentence that is front-loaded with the core purpose. Every word adds meaning about the expected output. However, it is missing important context, so it is not as effective as a slightly longer but more complete description. Still, for conciseness alone, it earns a high score.

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?

Given that this is a simple list tool with only two parameters and an output schema exists, the description does not need to explain return values. It provides a minimal but acceptable overview of the data returned. However, it omits any mention of the tool's scope (e.g., that it operates per course/assignment) and does not indicate any behavioral details, leaving the agent to infer from parameter names. This makes it marginally adequate.

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%, and the description does not compensate by explaining the parameters. While 'course' and 'assignment_id' might be self-explanatory in name, the description does not mention them at all, leaving the agent to infer their roles. The tool name and output fields imply a relationship, but the description adds no semantic value beyond the schema names.

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 'Who submitted what: user id, submitted_at, current score, attempt count.' clearly conveys that the tool returns submission data, listing users and their submission details. It is more specific than a bare tautology like 'List submissions' and aligns with the tool's name. However, it does not explicitly name a verb or distinguish from sibling tools like get_submission or classify_submissions, so it falls short of a 5.

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 provides no guidance on when to use this tool versus alternatives such as get_submission or classify_submissions. It does not mention any prerequisites, context, or exclusions. The only implied usage is that the tool lists submissions, but there is no explicit comparison or recommendation.

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