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

Goes well beyond the annotations: discloses the two-phase confirmation/confirmToken fallback, idempotent skip_existing re-runs, sidecar and EXIF/IPTC side effects, path determinism, and the performance cost of detail-page fetches. Annotations only say readOnly=false/destructive=false/openWorld=true, so this added context is exactly the value this dimension rewards.

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-loads the core action and filter story, then layers options; nearly every clause carries new information. It is dense and slightly run-on across the confirmation and metadata sentences, but no sentence is wasted.

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 no output schema, the description covers confirmation, idempotency, filtering, metadata side effects, and performance trade-offs. Its only notable gap is that it never describes the returned summary/counts on a successful run, aside from the preview-phase filenames and bytes.

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, but the prose adds cross-parameter meaning the schema does not: the filename_template slow/fast trade-off, how path_template composes with filename_template and collapses empty tokens, and the interplay of write_metadata/embed_metadata with skipped files.

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 ('Download full-resolution images of a student's artwork to a local folder') with the naming/scope behavior spelled out, which cleanly separates it from read-only siblings like artsonia_get_portfolio and artsonia_get_artwork.

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 clear when-to-use context: filter options, the confirmation-first rule, and an explicit alternative path ('use filename_template "{artwork_id}" for the fast id-only path'). It stops short of naming sibling tools for discovery, but the operational guidance is strong.

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 openWorldHint=true, covering the safety profile. The description adds that the response contains a count and a list of notices and gives examples of notice types (new teacher feedback, fan-club prompts), which is useful context beyond annotations, but it does not mention authentication requirements, rate limits, or pagination.

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, front-loaded sentence that packs the purpose, context (parent dashboard), and return shape without filler. It could be marginally more scannable, but it is efficient and 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 no-parameter read tool with no output schema, the description provides enough context: it states what the feed contains, where it appears, and gives examples of notices. It is nearly complete, though a hint about when to call it (e.g., to check for new activity) would close the remaining gap.

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 are no parameter semantics to explain. The baseline for zero parameters is 4, and the description correctly avoids discussing a nonexistent input schema.

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 ('Return') and resource ('notification/activity feed on the parent dashboard') and clarifies the payload ('with a count and the list of notices'). It does not explicitly distinguish itself from siblings like artsonia_get_feedback, which could also return teacher feedback, 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 explains what the tool returns but gives no guidance on when to use it versus alternatives such as artsonia_get_feedback or artsonia_set_notifications. There are no explicit when/when-not conditions or references to sibling tools.

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 openWorldHint=true, so the safety profile is covered. The description adds that comments are included in the result, which is genuine behavioral context, but says nothing about pagination, comment volume, or auth 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?

Two short sentences, front-loaded with the purpose and returning fields before the parameter note. No filler, every clause 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?

With no output schema, the description carries the burden of describing return values, and it does so by enumerating the fields. It is complete enough to call correctly, though it omits any note on result size or comment pagination.

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% and the single parameter is fully documented with a numeric pattern and source hint, so the baseline is 3. The description's 'from a portfolio' phrasing restates the schema's own 'from artsonia_get_portfolio' note rather than adding new semantics.

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 ('Get one artwork') and enumerates the returned fields (title, artist screen-name, view count, project, comments), so an agent knows exactly what comes back. It does not explicitly contrast itself with siblings like artsonia_list_comments or artsonia_download_artwork, but the singular-scope wording makes the distinction reasonably clear.

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?

'Pass an artwork_id from a portfolio' gives the provenance of the required input, which implies when the tool is usable. However, there is no explicit when-to-use/when-not guidance or named alternative (e.g., list_comments for bulk comment retrieval), leaving usage largely inferred.

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 openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral value by disclosing the shape of the result (current-year badges with name, earned status, criteria, and progress, plus prior-year badges), which tells the agent what data comes back. It omits pagination or any rate-limit/auth caveats, keeping it short of a 5.

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 sentences, no filler: the first states the resource and return contents, the second states the required input and where to get it. The most important information is front-loaded.

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 read-only, single-parameter tool with no output schema, the description supplies the return-value inventory an agent would otherwise lack, and the annotations cover safety. Nothing critical is missing, though the absence of pagination/scope notes leaves a small gap.

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 already documents its source (from artsonia_list_students). The description repeats that same fact without adding format, validation, or fallback detail, so the schema is doing the heavy lifting and 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?

The description gives a specific verb (List) and resource (Artsonia awards/achievement badges) and enumerates the returned fields, which is well beyond a restatement of the title. It does not, however, explicitly distinguish itself from overlapping siblings such as artsonia_get_activity or artsonia_get_portfolio, which the title's phrase 'awards & activities' could confuse an agent about.

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 only guidance is the parameter prerequisite: 'Pass the artist_id from artsonia_list_students,' which usefully points at the upstream tool. It says nothing about when to choose this tool over artsonia_get_activity or artsonia_get_portfolio, so usage is implied rather than stated.

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 openWorldHint=true, so the safety profile is covered. The description adds only the return shape (name + relationship), which is modest but useful given there is no output schema. No auth, rate-limit, or privacy nuance for fan data is disclosed.

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, zero filler, with the purpose front-loaded and the input hint immediately after. Every clause 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 single-parameter read tool with annotations covering the safety profile and no output schema, the description supplies both the action and the return fields. 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 coverage is 100% and the schema already documents artist_id as the student identifier, so the baseline would be 3. The description goes slightly further by specifying the provenance of the value (from artsonia_list_students), which is meaningful guidance the schema does not contain.

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 (fans in a student's fan club), and even previews the returned shape (name + relationship). An agent can distinguish it from siblings like artsonia_invite_fan or artsonia_list_students without opening any schema.

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 clear procedural context: 'Pass the artist_id from artsonia_list_students,' which tells the agent how to obtain the required input and implies a chained workflow. It stops short of stating when not to use it or naming a true alternative, so it is not a full 5.

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 openWorldHint=true, so the safety profile is known; the description adds value by disclosing the returned content, including per-item read status and authorship. It omits pagination, volume, and any rate-limit behavior, which keeps it from a top score.

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 sentences with zero padding: the first defines the output contents, the second delivers the actionable prerequisite. Front-loaded and every clause 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?

With no output schema present, the description usefully enumerates the fields returned, which is exactly what compensates for its absence. Remaining gaps are minor (pagination or result-size expectations for a list call).

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's schema text already states it is the 'Student artist_id (from artsonia_list_students)' and enforces a numeric pattern. The description only restates the same provenance, so by the high-coverage baseline this sits at 3.

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 teacher feedback left on a student's artwork') and even enumerates the returned fields (message, poster, timestamp, artwork, read status). It is clearly distinguishable from siblings like artsonia_mark_feedback_read, which mutates read state rather than listing.

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 tells the agent where the required identifier comes from ('Pass the artist_id from artsonia_list_students'), establishing a prerequisite call ordering. It does not, however, clarify when to prefer this over related list tools such as artsonia_list_comments or artsonia_get_activity.

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 openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: include_details fires one detail request per artwork, which is explicitly noted as slower and should be avoided for lean tiles — a real performance tradeoff an agent needs.

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 sentences, front-loaded with the return shape and then the actionable instruction. Every clause earns its place; the optional-flag caveat is compactly stated without repetition.

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 read-only list tool whose annotations cover safety, the description is nearly complete: it names the source of the required ID, enumerates returned fields for both modes, and flags the cost of the optional flag. Pagination or total-count behavior is unmentioned, which keeps it from a 5.

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 both artist_id and include_details fully, including the default and the concurrency behavior. The description reinforces rather than extends this, adding only the 'slower' performance note and the recommendation to leave it off — marginal value over structured fields.

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+resource ('List a student's artworks') and enumerates the returned fields (artwork_id, is_private, thumbnail). It also distinguishes itself from the sibling artsonia_get_artwork by being the collection-level tool and routes the caller to artsonia_list_students for the required ID.

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 explicit when-to-use guidance by stating where artist_id comes from and giving a clear when/when-not for include_details ('leave it off when the lean tiles are enough'). It does not explicitly contrast the tool against alternatives like artsonia_get_artwork, so it falls just short of a 5.

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 openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing the concrete shape of the returned profile (name, email, mobile, three notification opt-in states), which is not derivable from the annotation set. It does not mention auth requirements or behavior when fields are unset.

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 tight sentence with zero waste, front-loaded with the verb and resource and ending with the sibling pointer. Every clause earns its place by either naming the resource or routing the agent.

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 parameters, no output schema, and annotations covering the safety profile, the description does enough by enumerating the returned fields so the agent knows what a call yields. It stops short of noting authentication expectations or what happens when optional profile fields are absent, a minor residual gap.

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 per the rubric the baseline is 4. The description correctly implies no arguments are needed ('your account profile') and spends no words on non-existent parameters.

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 (Show) and resource (your Artsonia parent/fan account profile) and enumerates exactly what fields are returned: name, email, mobile, and notification opt-in states. It also names the sibling it complements (artsonia_set_notifications), so an agent can place it immediately among the 14 sibling tools.

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 closing phrase 'Read-only complement to artsonia_set_notifications' tells the agent this is the read side of a read/write pair, which is genuine routing guidance. It lacks any negative condition or prerequisite (e.g., what to do if the account is not signed in), so it falls short of explicit when/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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds real value on top: it discloses the network login step, the exact returned keys, and that the hint distinguishes no-creds vs bad-creds vs site-error. That failure taxonomy is genuine behavioral context not present in any structured field.

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?

One front-loaded sentence that packs the procedure, the return shape, the diagnostic value, and the read-only guarantee with no filler. Every clause carries information an agent would otherwise have to guess.

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 takes on the burden of describing the response and does so explicitly ({authenticated, transport, student_count} plus a plain-English hint). For a zero-param diagnostic, nothing needed to call or interpret it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and no syntax to document. Baseline 4 applies; the description correctly does not waste space restating an empty schema.

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?

Specific verb chain (confirm credentials, log in, fetch dashboard, report) plus the exact resource and outcome fields. It is unmistakably a diagnostic/auth-check tool, clearly distinct from the data-fetching siblings like artsonia_list_students or artsonia_get_portfolio.

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 implied by the 'healthcheck' framing and the credential-failure hints, so an agent can infer this is the pre-flight/setup verification tool. However, it never states when to run it versus going straight to a sibling, nor what to do with a failure result.

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 declare write/destructive/open-world, and the description adds substantial non-obvious behavior: an email is dispatched, a two-step confirmation fallback exists with a confirmToken that must never be invented or reused, and elicitation-capable clients take the prompt path instead. That is exactly the kind of side-effect and safety detail annotations cannot 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?

Front-loads the action, then the side effect, then the confirmation protocol and safety constraint, in three dense sentences. Slightly heavy on parenthetical asides but no wasted 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 mutation tool with no output schema, it covers the critical unknowns: that mail is sent, the preview-first fallback, and the token contract. It could say a bit more about what the phase-1 preview response contains or what success returns, but an agent has enough to call 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?

Schema description coverage is 100%, so every parameter including confirmToken is already documented in the schema. The description restates the name+email intent and the confirmToken rule but adds no syntax or sourcing detail beyond the schema (e.g., relationship_id sourcing stays in the schema). 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 a specific verb (invite) and resource (someone to follow a student's Artsonia portfolio), plus the effect (sends an invite email). It is clearly distinguishable from read-oriented siblings like artsonia_get_fans or artsonia_list_students.

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 explicit operating conditions: confirm first, use only authorized real addresses, test with @example.com. It does not name a sibling alternative (e.g., checking existing fans via artsonia_get_fans before inviting), so it stops short of full when/when-not routing.

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 openWorldHint=true, so the safety profile is covered. The description's only additional disclosure is the shape of the return content (author + text), which is useful given there is no output schema, but it says nothing about pagination, ordering, or empty-result behavior.

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 with zero filler, and the core purpose is stated first with the parameter note following. Nothing here could be cut without losing 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?

For a single-parameter annotated read tool this is nearly sufficient; it identifies the resource and the returned fields. The only minor gap is the absence of any mention of result volume, ordering, or how feedback-related siblings differ.

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% and the schema already documents artwork_id with its pattern and source (artsonia_get_portfolio). The description restates the same idea at a slightly higher level, so it adds little beyond the schema — the baseline 3 for fully-documented single-param tools.

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 (comments on an artwork) and even previews the returned fields (author + text). It does not explicitly name a sibling such as artsonia_get_feedback or artsonia_post_comment, so an agent must infer the split from the names alone.

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?

"Pass an artwork_id from a portfolio" gives a mild prerequisite for the parameter, but there is no explicit when-to-use or when-not-to-use guidance relative to similar tools like artsonia_get_feedback or artsonia_get_activity.

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 openWorldHint=true, so the safety profile is covered. The description adds useful context by listing the fields that come back, but says nothing about pagination, ordering, or what happens when the account follows no students.

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 sentences, no filler. The returned-field inventory comes first and the cross-tool role of artist_id is front-loaded as the actionable takeaway.

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 parameters and no output schema, the description's field list is the only disclosure of return shape and it covers the essentials (identity, school, grade, counts). Slightly incomplete on ordering and edge cases, but adequate for this simple read tool.

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 the baseline is 4. The description's mention of artist_id is about a field in the response used by other tools, not an input, which is helpful framing but not parameter documentation.

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 (students on parent/fan account), and enumerates the returned fields (artist_id, name, school, grade, counts). It also differentiates itself by naming the sibling tools that consume artist_id, so an agent can place it in the workflow.

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 implied rather than stated: by calling artist_id the selector used by portfolio, comments and fan tools, it hints this is the entry-point call for obtaining that id. There is no explicit 'use this when X, otherwise use Y' guidance or mention of prerequisites like being signed in.

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 establish it is not read-only and not destructive, and the description adds crucial context: the action is global (mark-ALL, no per-item control) and requires a confirmation step. It details both the elicitation-based prompt and the confirmToken fallback, going well beyond 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?

The description is front-loaded with the core action and then explains the confirmation behavior efficiently. It is dense but every sentence contributes, though it could be slightly more scannable with fewer parentheticals.

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 non-destructive mutation with a confirmation workflow and no output schema, the description covers the required behavior, the mark-all limitation, and both confirmation paths. Nothing essential to 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 coverage is 100%, and both parameters are fully documented in the input schema, including the confirmToken's intricate constraints. The description paraphrases the confirmToken flow but adds no semantic detail beyond 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?

States a specific verb and resource: mark the student's teacher feedback as read. It also explicitly notes the mark-ALL scope, distinguishing it from any per-item action and from the sibling artsonia_get_feedback.

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?

Clearly explains the context in which the tool is invoked and that it requires user confirmation first, including the two-step fallback flow. It does not name explicit alternatives or when-not-to-use cases, but none are obviously needed for a mark-read action.

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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description adds the non-obvious gating behavior (user confirmation, phase-1 preview, token-gated phase-2) which is genuine value beyond the flags. It stops short of explaining visibility of posted comments or any rate/permission limits.

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 sentences, front-loaded with the core action before the confirmation mechanics. Dense but every clause carries information; the second sentence is long yet justified by the non-standard two-phase protocol.

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 mutation tool with no output schema, the description covers the important non-obvious behavior (confirmation and the preview/confirmToken return shape) that the agent needs to call it correctly. Minor omissions such as visibility of the comment keep it from a 5.

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 already 100%, so baseline is 3; the description goes further by explaining when confirmToken applies and that the repeat call must use identical arguments, tying the token parameter to the confirmation flow rather than restating its schema text.

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+resource ('Post a comment on a student's artwork') that is immediately distinguishable from the read-side sibling artsonia_list_comments. An agent can identify the operation without opening any schema.

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 gives concrete invocation context: confirm-first behavior, the client-elicitation path, and the two-step preview/confirmToken fallback. It does not name when NOT to use it or point at alternatives, but for a single-purpose mutation tool the guidance is clear.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing the read-modify-rewrite mechanism, the guarantee that name/email/password are untouched, and the mandatory two-phase confirmation. It stops short of noting any rate limits, auth requirements, or what happens on partial failure.

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-loads the action, then the mechanism, then the confirmation flow in three tight sentences with no filler. Slightly dense in the confirmation sentence but every clause carries operational 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?

For a mutation tool with no output schema, it covers the safety profile, the mutation semantics, and the return preview ('preview shows the resulting opt-in state'). An agent has everything needed to invoke it correctly in either client mode.

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%, and the schema itself already documents each opt-in flag and the confirmToken's role in detail, so the description's parameter contribution is marginal. Baseline 3 applies when the schema does the heavy lifting; the description reinforces but does not extend it.

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 (turn the account's email opt-ins on/off) and enumerates the exact fields affected (news, artist activity, promos). This is clearly distinguishable from all siblings, which are read/download/comment operations.

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 describes the when and how: confirmation is required first, with a named fallback path (preview + confirmToken) for clients lacking elicitation, and states that confirmToken is passed only after user approval, never on the first call. The condition selecting each branch is spelled out rather than implied.

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