ScholarNet — Study Plan & Thesis Tools

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

Annotations already indicate non-readOnly behavior via readOnlyHint=false, and the description adds valuable context: the request 'counts toward their plan' and requires a connected ScholarNet account token. This discloses side effects and authentication prerequisites beyond what the annotations or schema state.

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?

Three sentences with no wasted words. The core action is front-loaded, followed by concrete use cases and the key prerequisite. Every sentence earns its place and the structure is easy to scan.

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?

For a simple 2-parameter tool with no output schema, the description is complete: it states what result to expect (step-by-step explanation), the account side effects, the prerequisite token, and appropriate use cases. Nothing essential is missing for correct selection and invocation.

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 the baseline is 3. The description adds beyond the schema by specifying the kinds of questions expected ('explain X', 'help me understand Y', homework/concept questions), which clarifies the intended input to the 'question' parameter beyond just 'The question to ask the tutor.'

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 begins with a specific verb and resource: 'Ask the ScholarNet AI Tutor a question and get a step-by-step explanation.' It also gives concrete use cases ('explain X', 'help me understand Y', homework/concept questions) that make it easy to distinguish from the sibling generation tools like generate_quiz or generate_flashcards.

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 clearly tells the agent when to use the tool via example question types and homework/concept guidance. It does not explicitly state when not to use it or name alternative sibling tools, so it stops short of a 5, but the use-case framing provides strong contextual selection guidance.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the safety profile is already known. The description adds useful context beyond annotations: the email requirement and that it is free. It does not disclose the output format or precise behavior (e.g., whether it returns all five styles at once or requires external interaction), but the core generation behavior is predictable; no contradiction with 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?

The description is a compact three sentences with the core action front-loaded. The 'Free' clause is mildly redundant but not harmful. Every sentence earns its place: purpose, requirement, and when-to-use.

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?

For a tool with 11 parameters and no output schema, the description covers the main selection cues (what it does, when to use, email requirement) but omits what the returned citation looks like and whether all five styles are returned at once. The schema handles parameter meanings, but the description could be more complete about the output contract.

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 the baseline is 3. The description adds only 'from the source type and details,' which maps to the schema's `type` and other fields, but it does not explain individual parameters or their relationships beyond the schema. It lists 'book, journal article, website' in the usage note, slightly reinforcing the `type` enum values, but no substantial additional meaning.

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 and resource: 'Generate a formatted citation for a source in five styles...' It also names the supported styles and source types, and clearly distinguishes from sibling tools (generate_study_plan, generate_thesis_statement), which serve different purposes. The title and description align with no ambiguity.

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?

Explicitly states when the tool should be used: 'Use it when a student needs to cite a book, journal article, website, or other source for an essay or paper.' It also gives a prerequisite (student email) and a condition (free). It does not explicitly contrast with alternatives, but the sibling tools are unrelated, so the use-case guidance is sufficient.

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

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

Annotations indicate a write operation that is not idempotent, and the description adds meaningful behavioral context by stating flashcards are saved to the connected ScholarNet account and that account connectivity is required. This goes beyond what the annotations alone convey.

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 compact and front-loaded, with the core action and inputs in the first sentence. The second sentence adds a crucial prerequisite without unnecessary detail. Every sentence earns its place.

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?

For a simple tool with no required parameters and no output schema, the description covers the key aspects: what it generates, from what inputs, where it saves results, and the account requirement. A minor gap is not explicitly stating that at least one of topic or notes should be supplied, but this is reasonably inferable.

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 baseline is 3. The description's mention of 'topic or pasted notes' aligns with the topic and notes parameters but adds little detail beyond the schema, such as count defaults or whether at least one source must be provided.

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 action: generating study flashcards from a topic or pasted notes and saving them to a ScholarNet account. This distinguishes it from siblings like generate_quiz and generate_citation by naming the specific resource and source inputs.

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 clear context for when to use the tool — when a user wants flashcards from a topic or notes — and includes an important prerequisite about needing a connected ScholarNet account. It does not explicitly name alternatives or exclusions, but the use case is well implied.

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

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

The annotations already indicate this is a non-read-only, non-destructive action. The description adds valuable behavioral context by explicitly stating the quiz is persisted to the student's account and that a connected account is a precondition, which goes beyond the annotation flags.

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 concise sentences with no filler. The core action and persistence side effect are front-loaded, and the account requirement is stated in a single follow-up sentence.

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, combined with full schema coverage and relevant annotations, gives an agent enough to invoke the tool correctly for a straightforward generation-and-save operation. The main gap is the lack of explicit alternative routing, but this is a minor omission given the simple interface.

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 input schema already fully documents all parameters. The description mentions the topic but adds no extra semantic detail about difficulty or numQuestions; the baseline of 3 applies because the schema carries the parameter documentation burden.

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 a specific verb ('Generate') and resource ('practice quiz on a topic') and adds an important scoping detail: the quiz is saved to the connected student's ScholarNet account. This distinguishes it from sibling tools like generate_flashcards or generate_study_plan.

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 the tool is for creating topic-specific practice quizzes and warns that a connected ScholarNet account is required, but it does not explicitly state when to prefer this over sibling tools or when not to use it. The use case is inferable but not directly guided.

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

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

The description adds meaningful behavioral context beyond annotations: the plan is 'sent/saved' to the student's email, the tool returns 'the plan summary and a shareable link,' and it is free. This clarifies the side effects and outcome without contradicting the 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?

Three concise, front-loaded sentences cover what the tool does, key requirements, outputs, cost, and when to use it. Every sentence adds value and none is redundant with the schema.

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?

For a simple two-parameter tool with full schema coverage and no output schema, the description is complete: it explains inputs, required email side effect, return value, pricing, and the target use case. No essential information is missing.

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 baseline is 3. The description reinforces that the email is required and the syllabus defines what to study, but it does not add significant new parameter meaning beyond what the schema already explains.

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 ('Create'), a clear resource ('personalized week-by-week study plan'), and the input sources ('syllabus, exam topics, or a description'). It is easily distinguishable from the sibling tool 'generate_thesis_statement' because it targets study plans rather than thesis statements.

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 explicitly says when to use it: 'Use it when a student asks for help planning their studying or exam prep.' It does not name the sibling or explicitly say when not to use it, but the use case is clear enough that an agent would pick it correctly.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds meaningful context by disclosing an auth-like requirement ('Requires the student’s email') and a cost constraint ('Free'). It also indicates that multiple output options are generated, which is useful beyond the structured 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?

The description is three short sentences with no filler. It front-loads the primary purpose, then lists constraints and the intended use case. Every sentence contributes useful information for tool selection and invocation.

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 the tool's moderate complexity and the absence of an output schema, the description gives enough context: what it generates, what inputs matter, a required identity element, and when to use it. It could be slightly more explicit about optional parameters and the exact return format, but it remains adequately complete for an agent.

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 all parameters well. The description adds only marginal clarity by grouping 'essay type' with its enum values and labeling 'stance' as optional, but it does not significantly expand on what the schema already provides.

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 a specific action ('Generate strong thesis statement options') and identifies the resource (thesis statement) plus the key inputs (topic, essay type, optional stance). It is immediately distinguishable from the sibling generate_study_plan because it targets essay thesis creation rather than study planning.

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 explicitly says 'Use it when a student needs a thesis or essay direction,' which gives clear when-to-use guidance. It does not explicitly name the sibling or state when not to use it, but the purpose is distinct enough that the use case is well understood.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by requiring a connected ScholarNet account and specifying the scope to the connected student's saved sets. It does not explain return format or error behavior, but this is minor for a zero-parameter read-only tool.

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 a single, front-loaded sentence that identifies the action, resource, and scope, followed by a useful prerequisite. There is no filler or redundant restating of the tool name.

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?

For a simple, zero-parameter, read-only list tool, the description is complete enough for correct selection and invocation. It names the exact resource, scope, and auth requirement, and no output schema is necessary for the agent to understand that this returns flashcard sets.

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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description does not need to add parameter-level detail.

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 uses a specific verb ('List') and clearly identifies the resource: connected student-saved flashcard sets in ScholarNet. The resource name naturally distinguishes it from sibling tools like list_my_quizzes and generate_flashcards.

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 states a clear prerequisite ('Requires a connected ScholarNet account'), which helps the agent know when this tool can be called. However, it does not explicitly contrast this tool with alternatives such as generate_flashcards or list_my_quizzes, so when-to-use vs. when-not-to-use guidance is only implied.

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

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

The description adds a behavioral prerequisite beyond the annotations by stating that a connected ScholarNet account is required, which is a meaningful operational constraint. The annotations already establish readOnlyHint, idempotentHint, and destructiveHint, and the description does not contradict them.

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 a single sentence that front-loads the core action and resource, then adds the essential prerequisite. Every word earns its place, with no redundancy or filler.

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?

For a simple zero-parameter list operation with strong annotations covering safety and idempotence, the description is almost complete. It covers what is listed and the key prerequisite, though it could arguably mention that it only returns the current user's saved quizzes, but the title already conveys 'my'.

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?

The tool has zero parameters, so there is no parameter information that the description needs to clarify. The description appropriately focuses on the tool's purpose and precondition rather than inventing parameter detail.

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 ('List') and a clear resource ('connected student saved quizzes in ScholarNet'), making the tool's function immediately understandable. It does not explicitly differentiate from siblings like list_my_flashcards or generate_quiz, but the 'saved quizzes' scope is distinct enough to avoid confusion.

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 a clear prerequisite ('Requires a connected ScholarNet account'), which gives context for when the tool can be used. It does not explicitly state when to use this tool versus alternatives such as list_my_flashcards or generate_quiz, leaving that inference to the agent.

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