clickedu-mcp

add_observation

Write one student’s session observation and optionally email the family; preview changes first, then confirm to save without altering other records.

Instructions

Write ONE student's free-text observation ('Observacions') for ONE session, optionally ticking "Enviar correu electrònic" so Clickedu emails the family. Single action only.

Without confirm=True it returns a PREVIEW (session, student, the current and new text, whether the family gets an email) and changes nothing. Call again with confirm=True only after the teacher approves. Every other student's attendance, homework and observations are replayed unchanged.

The text replaces this student's observation for this session; to add to an existing one, include the existing text (shown in the preview).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cgap": "<cgap>",
      "sessio": "<sessio>",
      "alu_id": "<alu_id>",
      "text": "<text>"
    },
    "name": "add_observation"
  }
}

Input Schema

Name	Required	Description	Default
`cgap`	Yes
`text`	Yes
`alu_id`	Yes
`sessio`	Yes
`confirm`	No
`notify_family`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations at all, the description carries the full burden and does it well: it discloses the preview/confirm gate, the destructive replace semantics, the optional family-email side effect, and that other students' attendance, homework and observations are replayed unchanged. It does not state permission or authorization requirements, nor whether a confirmed write can be undone, which are the two remaining behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the confirmation workflow, then the replace-vs-append gotcha. Every sentence contributes a distinct operational fact, and the final paragraph addresses the most likely misuse (losing existing text) before it happens.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the description covers the mutation workflow thoroughly for a preview-then-commit write. The gaps are limited to the unexplained cgap parameter and absent auth/permission notes, which are minor against the otherwise dense behavioral detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for six undocumented parameters. It adds real meaning for confirm (preview vs. commit), notify_family (Clickedu emails the family), and text (replaces, does not append), and implies alu_id/sessio via "ONE student...ONE session", but never explains cgap, which is opaque from its name alone and is a required parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Write ONE student's free-text observation") and bounds the scope tightly to one student and one session. That scoping, plus the explicit "Single action only", separates it from list/read siblings like get_session_notes and from send_message, which handles family communication in bulk.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear operating procedure: call without confirm to get a preview, then call again with confirm=True only after teacher approval. It also flags the email side effect as an opt-in. It does not name the alternative tool for appending to tutor conversations (add_tutor_conversation) or for reading existing notes, so the routing is implied rather than fully spelled out.

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