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

Goes well beyond the annotations: no confirmation step, writes confined to allowed download folders, idempotent re-runs via skip_existing, sidecar JSON and EXIF/IPTC embedding behavior, deterministic path templates, and that portfolio order is reliably newest-first. This is rich disclosure that heavily complements destructiveHint/openWorldHint.

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?

Purpose is front-loaded and each sentence carries operational information, but the dense single paragraph packs a lot of qualifiers, making it slightly heavy to scan. No wasted sentences, but tighter grouping into sub-points would help.

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 14-parameter mutation tool with no output schema, the description covers write scope, idempotency, metadata options, and pathing well. It doesn't describe reported return values (e.g. counts, private_excluded_count) which are left to the schema, a minor 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 coverage is 100% (baseline 3), but the description adds cross-parameter meaning: the speed trade-off between descriptive filename tokens and the id-only path, the path_template subfolder semantics, and the newest-first ordering that motivates limit. It reinforces rather than merely repeats the 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 and resource (download full-resolution images of a student's artwork to a local folder) and distinguishes itself from the read-only siblings like artsonia_get_artwork/artsonia_get_portfolio by emphasizing it writes files locally.

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?

Clear context for when to reach for it (bulk local archiving, with filters for class/project/grade/recency), and it explicitly routes between the descriptive-filename slow path and the '{artwork_id}' fast path. It does not name a sibling alternative or state when NOT to use it, so it stops 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, so safety of the operation is covered; the description adds real value beyond that by warning that the returned text is third-party authored and must be treated as data rather than instructions. It also discloses the shape of the payload (count plus list of notices). It stops short of mentioning pagination or freshness, keeping it at a 4.

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 purpose and followed by a security caveat that earns its place. No filler or restatement of the title.

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-parameter read tool with no output schema, the description covers what is returned (count plus list of notices) and the trust characteristics of that content. Nothing an agent needs in order 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?

There are zero parameters, so the baseline of 4 applies. The description correctly adds no parameter semantics because none exist, and nothing is misrepresented.

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 ('Return the notification/activity feed'), names the surface it comes from (parent dashboard), and gives concrete examples of notice types. An agent can distinguish it from the sibling artsonia_set_notifications (set vs. get) without opening either 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 phrase 'on the parent dashboard' implies the retrieval context, but there is no explicit when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as artsonia_get_feedback or artsonia_get_awards. Usage is inferable but not 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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description adds genuine value by warning that returned text is third-party authored, untrusted, and must be treated as data rather than instructions. That prompt-injection caution is exactly the kind of context annotations cannot express. It stops short of 5 by not mentioning whether comments are truncated or bounded.

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, front-loaded with the return payload and followed by the id requirement and the safety caveat. Nothing is repeated 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, enumerating the returned fields is the right compensating move, and the injection warning closes the biggest trust gap for open-world third-party content. The only remaining hole is whether the embedded comments are paginated or capped when an artwork has many.

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 there is only one parameter, so the schema already carries the semantics; baseline is 3. The description's 'from a portfolio' mirrors the schema's own note ('from artsonia_get_portfolio') and adds minimal new 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?

States a specific verb and resource ('Get one artwork') and enumerates exactly what comes back: title, artist screen-name, view count, project/assignment name, and comments. The contrast with list-style siblings like artsonia_list_comments is implied but never made explicit, 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 gives input sourcing guidance ('Pass an artwork_id from a portfolio'), which tells the agent where the required id comes from. However, it never says when to choose this over artsonia_download_artwork, artsonia_list_comments, or artsonia_get_portfolio — usage is only implied by the purpose statement.

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/openWorldHint, but the description adds a trait annotations cannot express: the returned text is authored by third parties, is untrusted, and must be treated as data rather than instructions. That is a concrete, actionable behavioral disclosure for an open-world read.

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 load-bearing: what it returns, where the parameter comes from, and how to treat the output. The safety caveat is placed last, after the operational facts, which is the right ordering.

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 only one required parameter and no output schema, the description covers everything an agent needs: the return contents, the parameter source, and the trust posture of the response. Nothing material is left unstated.

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 artist_id parameter is documented with a format pattern in the schema. The description adds the sourcing hint (fetch it from artsonia_list_students), which is mild extra value, but it does not add format or constraint detail beyond 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 and resource ('List the fans ... in a student's fan club') and even names the shape of the result (name + relationship). This clearly separates it from write-oriented siblings such as artsonia_invite_fan and from the comment/feedback 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?

Gives an explicit prerequisite: 'Pass the artist_id from artsonia_list_students,' which tells the agent how to obtain the required input and which sibling to call first. There is no explicit when-not guidance, but the read-only listing context 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered, yet the description adds valuable non-obvious context: the return content is third-party authored and untrusted, with an explicit instruction to treat it as data rather than instructions. It also discloses the shape of returned items. It does not mention pagination or rate 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, both earning their place: the first defines scope and payload, the second delivers the security-relevant instruction. Front-loaded and free of 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?

With no output schema, the description steps in by enumerating the fields each feedback item carries, and the prompt-injection warning covers the main risk of returning untrusted content from an open-world source. Only pagination/volume behavior is left unaddressed, which is minor for this 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?

Schema description coverage is 100% with a single parameter, so the schema already documents artist_id fully including its pattern. The description only reinforces the source of the ID (list_students) and adds no format or constraint detail beyond 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 (list) and resource (teacher feedback on a student's artwork), then enumerates the returned fields (message, poster, timestamp, artwork, read status). Distinguishable from close siblings like artsonia_list_comments and artsonia_mark_feedback_read 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?

Tells the agent where the artist_id comes from (artsonia_list_students), which is actionable context, but gives no when-to-use vs. when-not guidance against siblings such as list_comments or mark_feedback_read. Usage is only implied by the resource named.

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 and openWorldHint, yet the description adds meaningful behavior beyond them: the per-artwork detail-page fetch that makes include_details slower, and a security disclosure that returned text is third-party/untrusted and must not be followed as instructions. The prompt-injection warning is exactly the kind of context 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-loaded with the listing purpose, then usage and the parameter tradeoff, then the security note; every sentence carries information. Dense but not padded, though the inclusion of both the field list and the tradeoff makes it slightly heavy for a two-parameter tool.

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 steps in by naming the returned fields (both lean and detailed), and it covers the required-parameter source, the performance tradeoff, and the untrusted-content caveat. Nothing an agent needs 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%, so the baseline is 3; the description adds value by naming the origin of artist_id (artsnia_list_students) and by explaining the performance consequence of include_details, meaning the schema alone would not reveal. It does not add syntax beyond the schema, keeping it just above 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 and resource ('List a student's artworks') and enumerates the returned fields (artwork_id, is_private, thumbnail), which is more than a tautology. It references artsonia_list_students as the source of artist_id but does not explicitly contrast itself with single-artwork siblings like artsonia_get_artwork, so sibling differentiation is only partial.

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, actionable routing: get artist_id from artsonia_list_students, and an explicit when/when-not tradeoff for include_details ('leave it off when the lean tiles are enough'). It does not state when this tool should not be used in favor of an alternative sibling, so it stops short of full 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 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. The description adds valuable context beyond that: the output contains third-party untrusted text and should be treated as data, not instructions. This is a genuinely useful behavioral disclosure for prompt-injection safety.

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, front-loaded with purpose and followed by the required parameter and the safety caveat. No waste.

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 single-param read tool, everything needed is present: what it returns, the required input's provenance, and the untrusted-data handling. No output schema exists, so return-shape detail is modest but the author+text summary suffices.

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 artwork_id parameter is documented in the schema with its source tool. The description reinforces provenance ('from a portfolio') but adds little beyond the schema. Baseline 3 is appropriate.

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 (List) and resource (comments on artwork) with the return content (author + text) named. It is clearly distinguishable from the sibling artsonia_post_comment, which writes rather than lists.

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 states the prerequisite of passing an artwork_id from a portfolio, giving clear usage context. It doesn't explicitly exclude alternatives or mention the post_comment sibling, but the read/list intent is clear enough.

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 already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description adds meaningful context beyond them: execution is immediate with no confirmation step, the effect is bulk (all feedback), and it only alters the read state in the caller's own view. The last point sits in mild tension with destructiveHint=true but reads as useful scope clarification rather than a contradiction.

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 action and scope, then the behavioral caveats. No filler, no repetition of the title or 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 single-parameter mutation tool with no output schema, the description covers scope, immediacy, lack of confirmation, and the read-state-only effect — enough for an agent to invoke it safely. Minor gaps remain around reversibility and whether the change is idempotent, but nothing essential 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 parameter (artist_id) is documented in-schema with its pattern and source tool, so the description carries no additional parameter burden. It adds no format or constraint detail beyond the schema, which is the correct baseline-3 outcome when the schema does the heavy lifting.

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 ('mark the student's teacher feedback as read') and immediately disambiguates scope by declaring it a mark-ALL action with no per-item control. An agent can distinguish it from the read-oriented sibling artsonia_get_feedback without opening either 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 'mark-ALL action — Artsonia has no per-item control' clause tells the agent the condition under which this tool applies and warns that granularity is unavailable, which is genuinely useful routing guidance. It stops short of naming an alternative tool or stating explicit when-not-to-use conditions, so it is clear context rather than full 5-level 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 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses the full read-modify-write pattern, guarantees that name/email/password are left untouched, warns there is no confirmation step, and states it re-reads the profile to verify the change persisted. Those are exactly the behaviors an agent needs before firing a mutation.

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, each carrying distinct payload: the action, the partial-update/safety contract, then the execution and verification behavior. The purpose is front-loaded 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?

For a low-complexity three-flag mutation with no output schema, the description covers the side-effect profile, the partial-update contract, and the post-write verification. It omits what happens if no opt-in is supplied at all (no-op vs error) and any auth prerequisite, which are minor but real gaps.

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 a baseline of 3 applies, but the description adds the crucial semantics the schema omits: all three booleans are optional and omitted ones are left unchanged rather than reset to false. It also restates the category mapping (news, artist activity, promos), confirming which flag each parameter drives.

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 three opt-in categories, which map cleanly to the schema properties. An agent can distinguish this from read-side siblings like artsonia_get_profile without opening either 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 makes the usage context explicit: it is a partial update ('changes only the opt-in(s) you specify') that applies immediately with no confirmation step, so an agent knows this is the mutation path for notification settings. It stops short of naming when-not-to-use conditions or pointing to any alternative, but there is no close sibling to disambiguate against.

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