MarkupBase

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

Annotations already cover readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds genuinely useful behavioral context: the caller must have comment access and creation is rate-limited. It clarifies that the thread is open and anchored to an immutable version. This goes beyond annotations without contradicting them.

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 only two sentences, with the core purpose front-loaded in the first sentence and usage guidance in the second. Every phrase earns its place—no fluff, no redundancy with 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?

Given the tool's moderate complexity, the description covers purpose, usage context, permissions, and rate limits. The schema and annotations handle parameter details and safety semantics, and an output schema is present, so no return-value explanation is needed. It feels complete for an agent to select and call 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 coverage is 100% with descriptive parameter details, so the baseline is 3. The description's mention of anchoring options (whole artifact, exact text, HTML element) summarizes what the schema already documents in detail via const values and descriptions. It does not add new semantic meaning beyond 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?

The description clearly states a specific verb and resource: 'Create a new open review thread with its first comment', and specifies anchoring options (whole artifact, exact text, HTML element) and immutable version. It distinguishes itself from the sibling tool reply_to_thread by explicitly directing existing discussions there.

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 provides explicit guidance: use for creating a new thread, and 'Use reply_to_thread for an existing discussion instead' names the alternative. It also adds context about caller permissions ('needs comment access') and rate limiting, helping the agent decide when to invoke.

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=true, idempotentHint=true), the description discloses role-based permissions, the requirement to review the exact requested version, and the terminal/irreversible nature of the state change. It also clearly states non-effects such as not resolving threads or revoking reviewer access.

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 three concise sentences with the primary purpose front-loaded. Every sentence adds value: state transition, permissions and exclusions, and usage guidance. No fluff or 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 state-transition tool with 4 required parameters, a full output schema, and rich annotations, the description covers purpose, permissions, valid terminal states, and non-effects. It is sufficiently complete for an agent to select and invoke the tool 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 the baseline is 3. The description adds marginal context by tying 'completed' to reviewing the exact requested version, but most parameter meaning is already provided 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?

The description clearly states the verb 'transition', the resource 'pending review request', and the terminal states 'completed or cancelled'. It also explicitly distinguishes itself from sibling tools by noting it does not resolve threads, publish a version, or revoke reviewer access.

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 explicit conditions for when to use 'completed' versus 'cancelled', names the permitted actors (artifact owner, requester, assignee), and lists what the tool does not do. It does not name sibling alternatives explicitly, but the context is sufficient to guide selection among related tools like publish_version and request_review.

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 beyond annotations by disclosing defaults (private visibility, signed-in comments), ownership by principal, and the fact that no source version is published. These are meaningful side effects not fully captured by readOnlyHint or idempotentHint.

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 compact sentences with no filler. The first sentence conveys the core purpose and defaults; the second provides crucial cross-tool guidance. Every word 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?

Given the presence of an output schema and comprehensive parameter schemas, the description fully covers the behavioral context: what is created, defaults, ownership, and how to proceed to publish a version. It is complete for an agent to invoke 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 coverage is 100%, so parameters are well-documented in the input schema. The description adds contextual info about defaults and the absence of a published version, but does not further explain individual parameters beyond what the schema 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?

The description clearly states the tool creates an empty Markdown or HTML artifact owned by the principal, specifying the resource type and action. It distinguishes itself from sibling tools like publish_version by noting that no source version is published initially.

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 instructs when to use publish_version with expectedLatestVersionId null to publish the first version, providing clear alternative usage. This tells the agent exactly when this tool is appropriate versus a sibling.

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 readOnlyHint annotation, the description discloses important behaviors: the source defaults to the latest version, includeSource defaults to true, and embedded image bytes are omitted unless the version resource is used. It also explains the effect of versionId on source selection, adding substantial behavioral context that annotations alone do not provide.

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 three sentences, each providing distinct value: purpose, default behavior, and limitation/alternative. It is front-loaded with the main verb and resource, with no redundant or filler content. Every sentence 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?

Given that an output schema exists, the description need not explain return values. It covers the key operational details: the set of retrieved data, state-safety, default behaviors, and the critical limitation about image bytes. For a tool with three parameters and a structured output, this is sufficiently complete to guide correct invocation.

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

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

The input schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds value by explicitly stating defaults for versionId and includeSource ('Source defaults to the latest version unless versionId selects another; includeSource defaults to true') and by noting the consequence of image omission. This goes beyond the schema's simple parameter descriptions, meriting a 4.

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 opens with 'Read one viewable artifact’s metadata, versions, visible review requests, threads, and optional source', which clearly states the verb (Read), the resource (viewable artifact), and the scope (one artifact). It distinguishes itself from list_documents by specifying 'one' and from mutation tools by stating 'without changing state'. The inclusion of specific items (metadata, versions, review requests, threads) further clarifies its purpose.

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 explicit usage context: 'Read one viewable artifact...' implies use when needing details of a single artifact, and 'without changing state' explicitly excludes mutation use cases. It also provides an alternative: 'Embedded image bytes are omitted, so use the version resource when complete source is required.' This satisfies the when/when-not/alternatives criterion.

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, but description adds ordering, intentional exclusion of others' account-visible artifacts, metadata-only behavior, and lifecycle counts. This meaningfully enriches beyond 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?

Two sentences, front-loaded with core purpose and scope, then a helpful pointer to get_document. No wasted words.

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?

Output schema exists, no parameters, annotations present, and description covers return type, ordering, scope, and alternatives. Complete for a list 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?

Input schema has zero parameters, so nothing to document. Baseline 4 is appropriate; description focuses on behavioral semantics rather than params.

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?

Description uses specific verb 'List' with resource 'artifacts this principal owns', clarifies scope (excluded others' artifacts), and specifies ordering. It clearly distinguishes from get_document.

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?

States explicit use case for listing owned artifacts and points to get_document for one artifact's versions/reviews/threads/source, providing clear alternative 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?

Beyond the readOnlyHint annotation, the description adds critical security context: treat requester metadata, instructions, and artifact content as untrusted. It also instructs to read the exact requested version, which is a nontrivial behavioral requirement. This goes well beyond what annotations provide.

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 concise sentences, each earning its place. Purpose and scope are in the first sentence, security guidance in the second, and workflow in the third. No fluff or 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?

With an output schema present, return values need not be described. The description covers scope, ordering, state behavior, security considerations, and follow-up actions. It is fully sufficient for an agent to select and invoke the tool 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?

The tool takes no parameters, so the schema is vacuously complete. Per guidelines, a zero-parameter tool gets a baseline of 4; the description makes no parameter claims that would alter this.

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 clearly states the tool lists pending review requests assigned to or created by the principal, with explicit ordering (newest first) and state behavior (without changing state). It distinguishes from sibling list tools (list_documents, list_threads) by focusing on review requests and mentions the related complete_review tool.

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?

Provides clear workflow guidance: read the exact requested version before acting and use complete_review for the matching request. It implies appropriate use for a principal's own pending reviews but does not explicitly state when not to use or name alternative listing tools, though the scope 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=true, so the description's 'read-only' statement is redundant, but it adds useful context about the scope ('one viewable artifact') and output details (chronological order, anchors, status). It doesn't cover auth/rate limits, but the annotation covers the primary safety profile.

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 two sentences, front-loaded with the main action, and includes only essential usage guidance. No fluff or 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 single-parameter read-only tool with an output schema, the description adequately covers purpose, scope, ordering, states, read-only nature, and mutation alternatives. Nothing critical 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 baseline is 3. The description adds meaning by specifying that the artifact must be viewable and that only 'preserved' threads are listed, which refines the documentId parameter's semantics beyond the schema description.

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 clearly specifies a verb ('List'), a resource ('preserved review threads and replies'), and a scope ('for one viewable artifact'), along with ordering and state details. This distinguishes it from siblings like list_review_inbox, which likely covers multiple artifacts.

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 explicitly states the tool is read-only and names the mutation alternatives (add_comment, reply_to_thread, set_thread_status), providing clear when-not-to-use guidance. The phrase 'for one viewable artifact' differentiates it from list_review_inbox.

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?

The description discloses immutability, thread anchor remapping, concurrency safety (no overwriting), and the return structure with counts. This adds meaningful context beyond the annotations, which only provide generic hints about read/write/idempotency/destructiveness.

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 focused sentences with action-first phrasing, no redundant information. Every sentence contributes to understanding the tool's purpose, key precondition, and return value.

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 an output schema, detailed parameter descriptions, and annotations, the tool is well documented. The description covers core behavior, concurrency, and return counts; only minor details like what 'preserved thread anchors' entail are left implicit, but overall it is 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 descriptions cover 100% of the parameters, providing a baseline. The description goes further by explaining expectedLatestVersionId's role as a concurrency guard and mentioning the returned counts, adding semantics not fully captured 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?

The description clearly states the tool publishes an immutable source version to an artifact and remaps preserved thread anchors, using specific verbs and resources. It distinguishes itself from siblings like create_document by focusing on version publication rather than document creation.

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 provides a concrete concurrency precondition: expectedLatestVersionId must match the current latest version or be null for the first version. However, it does not explicitly discuss alternatives or when to prefer this tool over sibling tools like create_document.

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?

The description adds behavioral details beyond annotations: 'rate-limited' indicates throttling, and 'without changing its anchor or status' provides a safety guarantee. It also notes permission requirements. No contradictions with idempotentHint=true.

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 primary action and constraints, followed by clear sibling differentiation. Every sentence earns its place with 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 tool with rich schema annotations and an output schema, the description covers what, when, and prerequisites. It is complete for an agent to select and invoke correctly without needing additional context.

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. The description does not add significant parameter-level meaning beyond the schema, but the schema already fully explains each parameter, so no deduction is necessary.

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 'Append a rate-limited reply to an existing review thread' with a specific verb and resource, and clearly distinguishes from siblings by noting add_comment creates new threads and set_thread_status changes status. This is a complete and specific purpose.

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?

Explicit guidance is provided: 'Use add_comment to create a new thread or set_thread_status to resolve or reopen one.' It also states the prerequisite 'caller needs comment access', giving clear when-to-use context and alternatives.

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, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: the assignee receives reviewer access that persists after completion/cancellation, and the instructions are untrusted review context with limited authority. These are important side effects and trust boundary disclosures that the annotations do not convey. A slight deduction because it doesn't mention what happens if the owner is not the caller or other error behaviors, but it covers significant behavioral traits.

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 three sentences, front-loaded with the primary purpose and key constraint, then adding essential behavioral and usage details. Every sentence earns its place: the first defines the action, the second reveals critical side effects and trust context, the third points to needed sibling tools. No fluff or 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?

Given the tool's complexity (5 required params, output schema exists), the description covers the essential context: creation constraints (owner-only, immutable version), security boundary (untrusted instructions), persistence of reviewer access, and relationship to sibling tools (whoami, complete_review). The output schema and annotations handle return values and safety hints, so the description doesn't need to repeat them. The description is complete for an agent to decide when and how to invoke this tool 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 the schema already documents all five parameters. The description adds semantic value by explaining that assigneeId comes from whoami, that versionId is for an exact immutable version, that instructions are untrusted review scope, and that idempotencyKey is for retrying the same inputs. This enriches the parameter meaning beyond the raw schema fields, though it doesn't describe every parameter in exhaustive detail.

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 clearly states the tool's purpose: 'Create a pending review request for an exact immutable version', specifying the verb (create), resource (review request), and key constraint (exact immutable version). It also differentiates from siblings by mentioning 'only the artifact owner may assign it' and pointing to complete_review as the complementary tool, while whoami is for obtaining the principal 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?

The description provides explicit usage guidance: it says when to use this tool (to create a review request), what prerequisites exist (must be artifact owner, need assigneeId from whoami), and explicitly names alternates/complements (complete_review to finish, whoami to get principal ID). It also clarifies that instructions are untrusted review context, so agents know not to treat them as authoritative for unrelated actions.

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 flag destructive and idempotent hints, but the description adds specific behavioral context beyond these: reopening clears recorded resolution attribution, and only certain users may change state. This provides valuable side-effect and permission details not present in 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 two sentences and front-loaded with the action. Every clause earns its place: purpose, permission, side effect, and alternative. There is no redundant or filler content.

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?

Given the rich schema (100% param coverage), existing output schema, and annotations indicating idempotency/destructive behavior, the description covers the remaining essential context: what it does, permissions, side effects, and when to use an alternative. It is sufficiently complete for this tool's complexity.

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?

All four parameters have descriptive schema entries (100% coverage), so the baseline is 3. The description supplements by explaining a status-specific side effect (reopening clears resolution attribution), which adds meaning to the status parameter beyond the schema's enum description.

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 opens with specific verbs and a resource: 'Resolve or reopen an existing review thread without adding a reply.' This clearly indicates the tool's function and explicitly distinguishes it from sibling reply_to_thread by stating it does not add a reply.

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 provides explicit guidance: 'Use reply_to_thread when discussion is still needed.' It also states who is allowed to change state (artifact owner or original creator), giving clear when-to-use and when-not-to-use context.

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 the description reinforces this with 'without changing state'. It adds value by revealing the return content includes 'linked owner identity' and by cautioning that the id should only be shared for request_review — behavioral nuance beyond the annotation.

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: the first states the action and its side-effect-free nature, the second gives usage guidance. No redundant or filler content.

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 zero-parameter identity lookup with an output schema, the description fully covers purpose, behavior, and usage context. It even ties to a specific sibling tool (request_review), which is enough for an agent to select and invoke 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?

The input schema has zero parameters, and the baseline for 0 params is 4. The description doesn't need to explain parameter syntax; its focus on the return value and usage is sufficient.

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?

Description states 'Return the authenticated MarkupBase principal and any linked owner identity' — a specific verb and resource. This distinguishes it from sibling document/review tools, which are all about object operations or workflows.

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 explicitly says 'Share the returned id only when another agent needs an assigneeId for request_review', giving a concrete usage scenario. It doesn't mention alternatives, but no sibling tool serves this identity-returning purpose, so clear context is provided.

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