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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: the 20-project walk cap and the fact that truncation is reported, plus the shape of the result. Minor gap in not describing matching/fuzzy-match semantics.

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 compact sentences, front-loaded with purpose, then usage condition, then the operational caveat. Every sentence carries distinct information with no padding.

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 two-parameter read tool with no output schema, the description covers purpose, usage trigger, result fields, and the truncation limit. Nothing an agent needs to invoke 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%, so both parameters are already documented, including the example format '1001-300'. The description's 'or within one project' merely restates what project_id's schema description already says, adding no syntax or matching detail. 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 a specific verb and resource ('Find drawings by drawing number or name fragment') plus the scope (across the user's projects or within one), and even enumerates the returned fields. This clearly distinguishes it from siblings like xenmark_list_drawings or xenmark_list_projects.

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 an explicit selection condition: 'Use this when the user names a drawing rather than an id.' That routes the agent away from id-based lookups. It does not, however, explicitly contrast with xenmark_list_drawings, so the boundary with that sibling is left 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds one genuine behavioral fact beyond that: replies are truncated ('replies_truncated', 'up to 3 replies'), warning the agent that results may be partial. It says nothing about pagination behavior or the cursor's meaning.

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 sentence, front-loaded with the resource and scope, with no filler. The dense field enumeration is defensible given there is no output schema, though it makes the sentence long.

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?

Because no output schema exists, enumerating the returned fields is genuinely valuable and largely carries the return contract. However, it omits pagination mechanics (how next_cursor/cursor relate) and gives no context on when this list is preferable to sibling listing tools.

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 cursor, revision_id and include_replies_preview are all documented in the schema; baseline is 3. The description lightly corroborates the replies-preview behavior but adds no format, default, or constraint detail beyond what the schema already states.

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 phrase 'Comments on one revision' identifies the resource and scope, and the field list confirms it is a listing operation, but no explicit verb (list/retrieve) nor any differentiation from sibling tools like xenmark_list_replies or xenmark_review_summary is given. An agent can infer intent from the name, but the description itself reads as a return-shape spec rather than a purpose statement.

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?

There is no when-to-use guidance, no mention of what revision_id to supply, and no indication of how this differs from xenmark_list_replies or xenmark_review_summary. The one actionable hint ('quote comment_number to people') is about downstream use, not tool selection.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered without the description. The description adds the returned field set, which is useful given there is no output schema, but it says nothing about pagination behavior even though a cursor parameter exists.

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, no filler, with the resource scope front-loaded and the prerequisite appended. Every clause carries information an agent needs.

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 two parameters, full schema coverage, no nesting and no output schema, the description covers the essentials: what is returned and where the required id comes from. The only gap is that it does not mention the cursor/next-page flow, though the schema does document it.

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 baseline is 3, and the description goes beyond it by telling the agent where project_id must be obtained (xenmark_list_projects or xenmark_find_drawing). That sourcing guidance is real added meaning not present in 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?

It names the resource (drawings) scoped to one project and enumerates the returned fields, so an agent knows exactly what comes back. The listing verb is implied rather than stated, and it does not directly contrast itself with the similar-sounding siblings xenmark_list_revisions or xenmark_find_drawing, 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?

It states the prerequisite that project_id must come from xenmark_list_projects or xenmark_find_drawing, which implies the calling context. However, it never says when to prefer this list over xenmark_find_drawing for the same data, so the choice between siblings is left 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds nothing behavioral beyond that — notably it never mentions that results are paginated via cursor, which is the one behavior an agent needs to know here.

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?

It is a single compact sentence with no filler, which is good, but it is not front-loaded: it leads with a field inventory rather than the action, forcing the agent to reconstruct purpose from the 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?

With no output schema, enumerating returned fields (id, name, status, my_role, web_url, etc.) is genuinely useful and partially compensates. However, for a paginated list tool the absence of any pagination or result-size guidance leaves a real gap in what an agent needs 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% and the single cursor parameter is fully documented in the schema itself. The description does not reference the cursor or pagination at all, so it adds no parameter meaning beyond the schema — baseline 3 applies with only one optional param.

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 never states a verb — it reads as a colon-delimited field list rather than a statement of what the tool does. The only clue to purpose is the scope phrase 'Projects the user owns or is a member of,' which does meaningfully narrow the resource but leaves the operation implied by the tool name 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?

There is no when-to-use guidance, no mention of alternatives among siblings (e.g. find_drawing, recent_activity), and no note about when to page versus stop. The ownership/membership scope is the only contextual hint, which is thin for an agent choosing between list 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 readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds genuinely new context by disclosing pagination and enumerating the returned fields, though it omits ordering and any detail on how cursors behave across cycles.

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 with zero filler: scope, pagination, and return fields in a single clause. Nothing could be trimmed 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?

With no output schema, listing the returned fields is exactly the right compensation, and annotations cover the safety profile. Only ordering of results and the semantics of exhausting the cursor are unaddressed, which are minor gaps for a simple paginated read.

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 both comment_id and the opaque cursor fully documented in the schema. The word 'paginated' hints at the cursor's role but adds no syntax or format detail beyond the schema, 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 a specific verb (list) and resource (replies) with a precise scope ('on one comment') and enumerates the returned fields, which plainly separates it from the sibling xenmark_list_comments.

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: the agent infers it should call this when it already has a comment_id and wants that comment's replies. There is no explicit when-to-use, when-not-to-use, or guidance against reaching for xenmark_list_comments instead.

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 the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds a genuinely useful behavioral constraint: 'Files themselves are never available,' which stops an agent from expecting downloadable content. It stops short of describing ordering or pagination 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?

A single tight sentence: the resource comes first, then the returned fields, then the availability caveat. Nothing is wasted, though the field list is dense and would benefit from being deferred to an output 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 no output schema, enumerating the returned fields in the description is valuable and compensates well. The availability caveat covers the main agent trap. Minor gaps remain around result ordering and what distinguishes a revision, but nothing critical 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% and both parameters (drawing_id, cursor) are documented there, including the opaque cursor contract. The description adds only the implicit notion that revisions are scoped to a single drawing, 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 the specific resource and scope: revisions belonging to one drawing, and enumerates the fields each revision carries. This distinguishes it from xenmark_list_drawings and xenmark_list_comments, though it never names those siblings explicitly. A clear verb+resource pairing without sibling routing.

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 no when-to-use guidance and never references an alternative such as xenmark_find_drawing or xenmark_list_drawings. The need for a drawing_id implies the tool is scoped to an already-known drawing, but that is inference, not stated 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 establish readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuine value beyond that: the sort order (newest first), the exact shape of each row, and the operational constraint 'Use web_url for links - never build Xenmark URLs'. It does not mention pagination behavior, but for a read-only feed that is a minor omission.

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 resource and ordering before the row fields. The long field enumeration is dense but earns its place given there is no output schema. Minor cost: the middle sentence reads as a flat list rather than grouped by purpose.

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 full burden of describing the return shape, and it does so completely: actor, project, drawing, revision, comment, title, preview, mention labels, old/new status, read flag, timestamp, and deep link. Nothing an agent needs to interpret a row 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 both parameters (limit, unread_only) are fully documented in the schema itself. The description adds only the implicit framing of a notification feed with a default recency ordering; it does not clarify limit semantics or how unread_only interacts with the 'read' field it mentions.

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 ('the user's Xenmark notification inbox, newest first') and enumerates the event types it aggregates (comments, replies, mentions, status changes). This is clearly distinguishable from siblings like xenmark_list_comments or xenmark_list_replies, which return a different scope.

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 'notification inbox' — an agent can infer this is the cross-project activity feed rather than a per-drawing comment list. However, no explicit when-to-use/when-not guidance or named alternative (e.g., 'for full comment threads on one drawing, use xenmark_list_comments') is provided.

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, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: the 100-revision cap and the important caveat that inaccessible revisions are silently omitted (a partial-result behavior). It doesn't discuss rate limits or auth, but the silent omission note is a meaningful addition.

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 sentence: front-loads the purpose, lists output fields, states the cap, and ends with the access caveat. Every clause earns its place; no redundancy.

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 aggregation tool with full schema coverage and no output schema, the description covers purpose, output shape, limits, and an important edge case (silent omission of inaccessible revisions). It could mention ordering or whether counts are cumulative, but it is largely complete.

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 parameter is well-documented in the schema (array of revision UUIDs, min 1, max 100). The description reinforces the up-to-100 limit but adds little new syntax. Baseline for 1 param with full coverage is high, and the description corroborates the cap.

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 ('comment-status rollup for revisions') and enumerates the exact output fields (total_comments, open_count, progress_count, closed_count, last_activity_at). This clearly distinguishes it from siblings like xenmark_list_comments and xenmark_list_revisions which list rather than aggregate.

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 description - agents can infer to use this when they need aggregated comment status rather than raw lists. However, no explicit when-to-use or when-not-to-use guidance against alternatives like xenmark_list_comments is provided.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral content beyond that: the explicit negative scope ("Never returns e-mail, plan, billing or role") and the dependence on a configured token, which tells the agent not to promise data it cannot get.

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: purpose first, then the returned fields, then the exclusions. Every clause carries information and nothing is repeated from the schema or annotations.

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 must describe returns itself, and it does so by naming the three fields and the four it never returns. It does not cover failure modes (e.g., missing/expired token) or the return envelope, which is a minor gap for an otherwise self-contained zero-parameter 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 per the rubric the baseline is 4. There is no parameter semantics to clarify and the description correctly spends no words on inputs, instead describing outputs.

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 ("Identify") and a precise resource ("the Xenmark account behind the configured token"), then enumerates the returned fields (user_id, display_name, company). This is unmistakably distinct from the list_*/review/find siblings, which all operate on projects, drawings, revisions, or comments rather than session identity.

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 "behind the configured token" makes the usage context clear: this answers questions about the current session's identity rather than any artifact, so it has no overlap with the list/find siblings. It stops short of an explicit when-to-use/when-not statement or naming an alternative, which keeps it below a 5.

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