study_connect_school

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds real context: it creates server-side state (a job_id), it is interactive rather than headless, it permanently sets up a reusable profile, and session expiry can force a re-login. That is meaningful disclosure beyond the annotations, though it says nothing about permissions or concurrency on the same profile.

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, front-loaded with the action, then mechanics, then the return value and follow-up. Each sentence carries information, though the 'without a host browser, screenshots or Save As' clause is slightly dense and could be trimmed.

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?

With no input schema fields and no output schema, the description fully carries the burden: it explains the interactive step, the reusable-profile side effect, the returned job_id, the polling sibling, and the expiry caveat. An agent has everything needed to invoke it correctly.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description's mention of job_id is an output, not an input, so no further parameter semantics are needed.

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?

States a specific verb and resource: starting an interactive campus login in a dedicated local Chrome profile. This is clearly distinguishable from siblings like study_school_status or study_school_job, and the description explicitly names study_school_job as the polling companion.

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?

Explains the operating model: the user enters credentials/MFA directly, and later course/resource/download jobs reuse the profile without a host browser. It also tells the agent to poll study_school_job, but it does not state when to avoid this tool (e.g., if a session already exists) or how to detect that case beyond the expiry note.

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