Lessonspace MCP by usefulapi

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's real contribution is disclosing the shape of the payload it returns — space, participants, guests, tags, summary, recording state. With no output schema present, that enumeration is genuinely load-bearing, though error behavior (e.g. unknown uuid) is unaddressed.

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 short sentences, front-loaded with the identification and scope, followed by the raw endpoint for API-aware callers. Nothing is padded.

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 single-parameter read tool with annotations covering safety and no output schema, listing the returned facets makes the definition largely complete. Minor gaps remain around error/not-found behavior and whether the response is nested or flat.

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% and the schema itself tells the agent the value is the `uuid` field from lessonspace_list_sessions. The description only repeats 'by uuid,' adding no format or constraint detail beyond the structured field.

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 ('One session by uuid') and enumerates the returned facets (space, participants, guests, tags, summary, recording state), which separates it from list_sessions and, by omission of the media itself, from get_session_recording. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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?

'One session by uuid' implies the single-item fetch case as opposed to list_sessions, but there is no explicit when-to-use or when-not-to-use guidance and no mention of prerequisites (e.g. needing a valid uuid from list_sessions, which only appears in the schema).

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 and destructiveHint=false, yet the description adds real context the annotations cannot carry: the three-value status semantics, the retry timing for a not-yet-ready recording, and an explicit entitlement warning that the returned URL is an access link to be shared only with someone entitled to watch. That is substantive behavioral disclosure beyond the structured fields.

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?

Roughly four short sentences, front-loaded with the return value, then the status state machine, then the sharing caveat, then the endpoint. Every sentence carries distinct information with no restatement of the title or 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?

There is no output schema, so the description correctly carries the return-value burden itself by explaining the URL and the status field with all three enumerated outcomes. For a single-parameter read tool this is fully complete; nothing needed to call it correctly 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% and the single 'session' parameter is already documented in the schema, including a pointer to the uuid field from lessonspace_list_sessions. The description adds no format, syntax, or sourcing detail beyond that, so the baseline of 3 applies.

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 and resource: it returns the playback URL of a session's recording, and it names the return field ('The playback URL of a session's recording'). The resource word 'recording' cleanly separates it from the sibling lessonspace_get_session_transcript without either schema being opened.

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?

It gives concrete usage guidance keyed to state: on 'preparing' the agent should 'ask again in a minute', and on 'no_recording' it knows no URL will exist. It does not, however, explicitly route the agent between this tool and alternatives such as lessonspace_get_session_transcript or lessonspace_get_session, so there is no when-not 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true. The description adds genuinely useful behavior beyond that: the URL is signed and access-bearing, so it must only be handed to an entitled reader, plus the precondition on transcription.

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 short sentences, each carrying distinct information (return value, precondition, security caveat), with the important scoping constraint near the front. The trailing raw endpoint path is mildly redundant but still informative.

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 output schema, the description correctly explains the return value and adds the precondition and a sharing caveat. It omits whether the signed URL expires or how long it remains valid, which would be the remaining gap for a credential-bearing return value.

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% and the single parameter is fully documented in the schema (session uuid from lessonspace_list_sessions). The description adds only that session appears in the URL path, so the baseline 3 applies.

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 precisely what the tool returns: a signed download URL for a session's transcript. It implicitly distinguishes itself from the sibling lessonspace_get_session_recording by naming the transcript resource, though it never names that sibling explicitly.

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?

Gives a clear precondition for use: transcription must have been switched on at launch (transcribe=true). It does not name alternative tools or describe what to do when the precondition fails, so it stops short of full routing 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 already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, and the description is consistent with them while adding genuinely non-structured context: the link is a live credential for a real person, must never be posted elsewhere, and re-calling issues a fresh link. It stops short of explaining what 'destructive' actually destroys or any auth/permission requirements.

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?

Front-loaded with the operation type, then the credential warning, then the repeat-call semantics, then the secret caveat. Four sentences, each carrying distinct information, with no boilerplate or restated 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 15-parameter mutation tool with nested objects and no output schema, the description covers the mutation semantics, the returned join link, and the credential risk. It does not flag the region-picking pitfall or note that most parameters beyond `id` are optional, but the essentials for correct invocation are present.

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 93%, so the schema already documents nearly every parameter (id, user, server region, not_after, etc.) and the description adds no per-parameter meaning. The only non-schema detail, that the server's own `secret` is never returned, concerns output rather than inputs.

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 ('create a space, or reuse the one with the same id') plus the outcome ('get a join link (client_url) for one participant'). The 'WRITE:' prefix immediately separates it from the read-only siblings like lessonspace_list_spaces and lessonspace_get_session.

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?

Gives a clear context for use and the key reuse condition ('calling again with the same id reuses the space but issues a new link'), and warns it is 'not safe to repeat blindly'. It does not name an alternative tool or an explicit when-not-to-use case, but no sibling offers launch capability, so the gap is minor.

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 readOnly/non-destructive/openWorld, so the bar is lower. The description adds real context beyond that: 'Newest first as Lessonspace orders them', the sensitive-data warning about playback_url and participant emails, and the underlying GET endpoint. It stops short of describing pagination behavior beyond what the page param already implies.

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?

Front-loaded with purpose, then filters, then ordering, then a privacy caveat. Every sentence carries information, though the returned-field enumeration is long and the privacy note could be marginally tighter.

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 output schema, the description usefully enumerates the returned fields (name, uuid, times, participants, tags, recording state) and adds ordering and privacy guidance. Combined with 100%-covered parameters and read-only annotations, an agent has nearly everything needed; only pagination nuances are left implicit.

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 18 parameters with types, bounds and examples. The description's filter list (time, duration, participant, space, launch id, tags) mirrors those parameters without adding syntax or semantics beyond the schema, making 3 the correct baseline.

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 ('List') and resource ('the organisation's sessions') and even defines the domain term ('a session is one meeting held in a space'), then enumerates the returned fields. It does not explicitly distinguish itself from the sibling lessonspace_list_space_sessions, but the org-wide scope is implicit in 'the organisation's sessions'.

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?

It lists the available filters ('time, duration, participant, space, launch id or tags') and the ordering, which implies how to narrow results, but it never states when to prefer this over lessonspace_list_space_sessions or lessonspace_get_session. Usage is inferable rather than explicit.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds genuine behavioral context beyond them: which fields come back (tags, lock state, region, recording/transcription settings) and the warning that a space's url is a way in and should be treated as sensitive. It does not mention pagination limits or result-volume expectations.

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 tight sentences plus the endpoint path, with the core purpose front-loaded before the sensitivity note. The dense comma-run of nine return fields is slightly listy but each item earns its place and there is no 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?

There is no output schema, so spelling out the returned field set is valuable compensation and it is done here. Combined with annotations covering safety and a fully documented parameter schema, an agent has enough to call this correctly; only usage routing among the sibling list tools is absent.

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% and every one of the 9 parameters is documented in-schema (including the tag_key/tag_value pairing and the date_after/date_before overlap note). The description adds no parameter-level meaning beyond that, so the baseline of 3 applies; the fields it lists are return values, not inputs.

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 and resource ('List the organisation's spaces') and even defines the resource ('persistent rooms'), then enumerates the fields returned. It is clearly the list-spaces tool rather than a session tool, but it never names the adjacent siblings (lessonspace_list_sessions vs lessonspace_list_space_sessions) that an agent could confuse it with.

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?

No explicit when-to-use or when-not-to-use guidance and no named alternative is given. Usage is only implied by the schema's optional filters (search, tag_key, date_after, etc.), which lets a reader infer that this is an unfiltered-with-optional-narrowing list.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real value by disclosing what comes back: a join/leave/idle event log with timestamps plus a list of currently connected users, which the annotations do not 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?

Three short sentences with no filler: the returned data first, the filter-reuse note second, the endpoint third. Everything is front-loaded and each clause carries distinct information.

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?

There is no output schema, and the description compensates reasonably by summarizing the return payload and pointing at a sibling for filter semantics. It leaves minor gaps, such as pagination behavior beyond the schema's own page description, but is otherwise sufficient for correct 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 18 parameters are individually documented and the baseline would be 3. The description earns a bump by supplying a collective cross-reference ('same filters as lessonspace_list_sessions'), which is information the schema itself cannot express and helps the agent reason about the filter set as a whole.

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 names the resource (sessions of one space) and the returned payload (join/leave log, current connected users), which is more specific than the title alone. It also implicitly distinguishes itself from lessonspace_list_sessions by scoping to a single space, though it never states that contrast explicitly.

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 mention that it uses the same filters as lessonspace_list_sessions implies the two tools are related, and the space-scoped framing hints at when to pick this one. However, there is no explicit when-to-use/when-not or direct routing instruction against the sibling list_sessions tool, leaving the choice to inference.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds a genuine disclosure beyond structured data: that names and emails are personal data, which signals handling constraints. It does not mention pagination limits or rate limits, but the privacy warning is meaningful added context.

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 tight sentences with the returned-field list and the privacy note front-loaded, plus the endpoint. Nothing is padded, though the enum list inside the prose ('teacher, student, admin') slightly duplicates 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?

With 5 optional filter parameters, no output schema, and no required params, the description carries the burden of describing the response, and it does so by enumerating the returned fields. The main gap is the absence of any guidance on how the filters combine.

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 page, role, search, space_ids and session_ids. The description adds no syntax, format, or interaction detail for these filters, so the baseline of 3 applies.

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 ('List the organisation's users') and enumerates the returned fields (id, name, email, role, active state, external id), which goes beyond a bare restatement of the title. It does not explicitly differentiate itself from siblings, though the user/org scope is distinct from list_sessions/list_spaces.

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?

Usage is only implied: 'List the organisation's users' with a trailing endpoint. There is no statement of when to prefer this tool, no note on combining filters, and no mention of alternatives (e.g. whether a single-user fetch exists among siblings).

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 cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower. The description still adds real context beyond them: the name is always transmitted because the API requires it, empty-list fallback to org policy, and omission semantics. It does not, however, explain the destructive aspect the annotations imply.

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?

A single dense paragraph with the operation class front-loaded ('WRITE:'), the primary and secondary actions in order, and the endpoint last. No filler sentences.

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 no-output-schema mutation tool whose annotations cover safety, the description supplies action scope, optionality, fallback behavior, and the endpoint. It omits response format and any auth/permission requirements, but nothing essential for correct invocation 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 schema already documents all three parameters including the enum values and the []/omit semantics. The description mostly restates the recording_access_policy behavior and only genuinely adds the 'name is always sent' constraint, so baseline 3 applies.

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 two specific operations (rename a session, set recording access) on a named resource and flags the operation class with 'WRITE:'. This is clearly distinguishable from the read-oriented siblings (get_session, list_sessions).

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?

It clarifies optional-vs-required behavior: recording access is optional, an empty list falls back to org policy, and omitting it leaves the value unchanged. It gives no explicit when-to-use-vs-alternative routing, but the read/write split against siblings is implied by 'WRITE:'.

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