NotePom

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

Annotations already convey mutability (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds that only exact pending invitations addressed to this account are accepted, but it does not disclose side effects, failure behavior, or whether accepting creates a persistent collaboration. No contradiction with 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?

One tight sentence with no filler. The key qualifiers 'exact', 'pending', and 'addressed to this account' are efficiently packed.

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?

The operation is simple and annotations cover idempotency and non-read-only behavior, but the description lacks guidance on idempotencyKey generation, how to obtain a valid invitationId, and what happens after acceptance. Adequate for a basic tool but with clear 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 description coverage is 0%, so the description carries the full burden for explaining parameters. It never names invitationId or idempotencyKey, and idempotencyKey's purpose is entirely unexplained. 'Exact pending invitation' loosely maps to invitationId, but the agent gains little guidance beyond the raw 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 uses a specific verb ('Accept') and resource ('pending collaboration invitation addressed to this account'), making the tool's purpose unmistakable. It naturally distinguishes this from sibling tools like invite_collaborator, list_collaboration_invitations, and revoke_collaboration_invitation.

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 implies the tool is for accepting only exact, pending invitations sent to this account, but it does not explicitly state when to use it versus alternatives. There is no mention of checking list_collaboration_invitations first or avoiding use for revoked/expired invitations.

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 indicate this is a non-read-only, idempotent, non-destructive operation. The description adds useful context about the link being short-lived and including NotePom return paths, but it leaves the external Stripe API side effect implicit. This is adequate but not especially rich.

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 a single, front-loaded sentence with no filler and no duplication of the title. Every word adds relevant 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?

The output schema and annotations cover return values and idempotency/safety traits, so the description does not need to repeat those. However, the absence of usage guidance and parameter semantics makes the overall definition only minimally complete for an agent that must 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?

Schema description coverage is 0%, and the description provides no explanation of 'idempotencyKey' or 'country'. The agent gets no semantic help beyond raw schema constraints, so the description fails to compensate for the missing 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?

The description states a specific verb ('create') and a specific resource ('short-lived Stripe Connect onboarding link'), and adds NotePom return paths. This clearly distinguishes it from the listed sibling tools, none of which perform Stripe Connect onboarding.

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 does not state when to use this tool, what prerequisites exist, or which alternatives might be preferred. The only context is what the tool does; there is no explicit usage guidance or exclusion of other scenarios.

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 two useful behavioral facts beyond the annotations: the operation is reversible, and it must follow explicit client confirmation. This usefully qualifies the destructiveHint=true annotation without contradicting it.

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 tightly written sentence with no filler; the core action and key qualifiers come first, and the precondition is appended without diluting the point.

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?

The description is complete for a low-complexity, two-parameter tool, especially since an output schema exists and annotations cover idempotency/destructive behavior. The main remaining gap is the undocumented idempotencyKey semantics, which keeps it from a 5.

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

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

With 0% schema description coverage, the description must carry parameter meaning, but it only explains productId ('by productId') and says nothing about the required idempotencyKey or how it should be generated/used. The name hints at its purpose, but the required parameter is left undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('stop'), a precise resource ('seller-owned listing'), and the lookup key ('productId'), and the qualifier 'reversibly' distinguishes it from permanent delete/trash operations in the sibling set. This is enough for an agent to know what the tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the precondition 'after client confirmation' and restricts use to seller-owned listings, giving an agent context for when the call is appropriate. It does not name alternative tools or explicitly say 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 and idempotentHint=true, so the description adds value by mentioning that inherited access is checked before returning data and that the response includes Pretext documents. This gives the agent useful behavioral context beyond the structured 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 a single, tightly worded sentence that places the core action and resource first. Every phrase earns its place by adding scope or behavioral nuance.

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 read operation with a rich output schema and safety annotations, the description covers the essential distinguishing behavior: returning Pretext documents and checking inherited access. It could further clarify what 'inherited access' means or how access failures are surfaced, but it is otherwise adequate.

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 0%, so the description needed to compensate by explaining how noteId and workspaceId relate to the operation. It does not; it only restates the general read action. The parameter names are fairly self-explanatory, but the description itself adds little semantic value for the inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action ('Read') and a specific resource ('an exact collaboration note and its Pretext documents'), which is more informative than the title alone. It does not explicitly differentiate from sibling tools like get_note, but the collaboration-specific scope makes the purpose reasonably distinct.

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 explicit guidance on when to use this tool versus alternatives such as get_note or list_shared_with_me. It implies a read use case but provides no exclusions, conditions, or comparison to sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the read-only nature is covered. The description adds useful behavioral context by stating the listing must be owned by the authenticated seller and by imposing the exactly-one-of-productId-or-slug constraint, which is not enforced by the schema's required fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is one front-loaded sentence with no filler. It states the resource, the ownership constraint, and the invocation rule clearly and efficiently.

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 low complexity and the presence of an output schema, the description is nearly complete: it states what the tool returns, the ownership scope, and the required identifier constraint. It loses a point because the schema lacks a required/oneOf contract, and the description does not explicitly address what happens when neither or both identifiers are supplied.

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 0%, so the description must compensate. It adds the crucial selection rule: exactly one of productId or slug must be provided. It does not separately explain the meaning or format of slug versus productId, but the parameter names and schema constraints provide partial context.

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 uses a specific verb ('Return'), a specific resource ('marketplace listing'), and an ownership scope ('owned by the authenticated seller'). The singular 'one' also distinguishes it from listing-oriented list tools and other getters in the sibling set.

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 implies the intended use: fetch a single listing owned by the authenticated seller using one of two identifiers. It does not explicitly mention when to choose this over siblings such as validate_listing_readiness, disable_listing, or list_seller_sales.

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, and non-destructive behavior; the description adds that the operation returns Markdown and preserves the underlying Pretext document, which is a meaningful behavioral guarantee beyond the annotations. No 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?

One efficient sentence, front-loaded with the action, with no filler or repetition. Every phrase adds information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with rich annotations and an output schema, the description covers core behavior, but it lacks context for distinguishing a NotePom note from collaboration notes or files, and the 'Pretext document' relationship is unexplained.

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 0% and the description does not explain what noteId should refer to or how to obtain it; it only implies a NotePom note. The parameter name and length constraints carry most of the 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 'Read', target resource 'one NotePom note', and output format Markdown, with distinctive mention of preserving the underlying Pretext document. It is clear enough to be told apart from read_file or get_collaboration_note, though it does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over siblings like get_collaboration_note or read_file, and no prerequisites or context are given. The only implicit signal is the function name, so an agent has no explicit selection criteria.

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 tool read-only, idempotent, and non-destructive. The description adds useful behavioral context by explaining what the discovery returns, including the signup mode and safe bootstrap sequence, without contradicting 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?

Two sentences with the sequencing instruction front-loaded and no redundant phrasing. Every clause contributes a distinct piece of information about what the tool does and what it returns.

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 capabilities tool with an output schema and complete safety annotations, the description is sufficient. It names the exact outputs and tells the agent to invoke it first, giving enough context for correct use.

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 has zero parameters, so no parameter documentation is needed; the baseline of 4 applies. The description reinforces that this is a no-input discovery call by framing it as an inspection and retrieval operation.

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 discovery action with three concrete outputs: persistent workspace memory, autonomous-agent signup mode, and a safe bootstrap sequence. Clearly distinguishable from sibling tools, which are all domain operations rather than a capabilities probe.

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?

Leading with 'Call this first' gives an explicit sequencing instruction that tells the agent when to invoke this tool. It does not enumerate alternatives or exclusions, but for a zero-parameter bootstrap discovery call this is a minor gap.

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 this as a safe, read-only, idempotent operation, so the description does not need to repeat those traits. It adds the term 'bounded' and clarifies the returned content is Stripe Connect seller status and commission info, but 'bounded' is vague and no additional behavioral context like data freshness or access requirements is provided.

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 a single efficient sentence with no filler. However, the word 'bounded' is ambiguous and could confuse an agent, preventing a perfect score.

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 zero parameters, an output schema present, and annotations covering safety and idempotency, the description is mostly sufficient for invoking the tool. It lacks richer context about what 'bounded' means or how the status relates to Stripe Connect onboarding, but the available structured metadata compensates for most 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?

The tool has zero parameters and an empty schema, so the baseline is 4. There are no parameter semantics for the description to clarify, and nothing in the description contradicts or complicates the 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?

The description clearly states the tool returns seller status and commission information for Stripe Connect, using a specific verb and resource. It does not explicitly differentiate itself from related siblings like create_stripe_onboarding_session or list_seller_sales, but the resource scope is clear enough for basic identification.

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 guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as whether a seller account must already be onboarded. Usage context is only implied by the tool name and description, so an agent has to infer when this is the right call.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful nuance: an email invite can precede account creation, and the recipient must accept after signing in, meaning access is not granted immediately. This goes beyond what annotations state, and no contradiction is present.

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 with no filler, stating the action first and the behavioral caveat second. Each sentence earns its place and is easily scanned by an 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?

The core action and a key non-obvious behavior are covered, and annotations supply idempotency and side-effect profile. However, with no output schema and several required parameters undocumented in the description, an agent relies heavily on parameter names. The lack of explicit mention of the target entity (note/folder) or what the tool returns leaves moderate 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 description coverage is only 20% (only identity has a description). The description repeats and slightly extends identity semantics (username or email, pre-account invitations) but says nothing about workspaceId, entityType, entityId, or idempotencyKey. The description fails to compensate for the gaps left by 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 opens with a specific action: 'Invite a collaborator by NotePom username or email.' It names the verb, the resource, and the accepted identity types. This clearly distinguishes the tool from siblings like accept_collaboration_invitation and revoke_collaborator.

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 useful context: email invitations can be created before the recipient has an account and require explicit acceptance. This implies the invitation lifecycle and that acceptance is a separate step. However, it never names alternative tools such as accept_collaboration_invitation or revoke_collaborator, nor states when not to use this tool.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe, non-mutating behavior is established. The description adds a key behavioral detail: only 'pending' invitations are returned, and only those addressed to the authenticated account. It does not discuss whether expired invitations are included, but 'pending' is meaningful and non-redundant with 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 a single, focused sentence that states the verb ('List'), the object ('pending collaboration invitations'), and the scope ('addressed to the authenticated account'). There is no filler, and every word contributes to operational clarity.

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 zero-parameter schema, rich annotations, and an output schema, the description covers the essential behavioral contract: what is listed and for whom. It could mention what an agent should do after listing (e.g., present choices to accept or revoke), but that is arguably inferable from sibling names. The description is complete enough for a simple, safe read-only listing operation.

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 100% schema description coverage, so there are no parameters to explain. The description still clarifies the implicit scope of the listing (pending invitations for the authenticated account), which is the main semantic content. Baseline 4 for zero-parameter tools 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?

The description identifies a specific action and resource: 'List pending collaboration invitations addressed to the authenticated account.' It clearly distinguishes the tool from siblings such as invite_collaborator, accept_collaboration_invitation, and revoke_collaboration_invitation by focusing on listing pending invitations for the authenticated account. It does not explicitly contrast with list_shared_with_me, but the 'collaboration invitations' scope is reasonably specific.

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 context by saying 'addressed to the authenticated account,' which implies the tool shows invitations sent to the user and not invitations they have sent. It does not explicitly say when not to use it or name alternatives, but the context is sufficient for an agent to distinguish it from related collaboration tools. A small gap is lack of explicit guidance about filtering or pagination, but the zero-parameter schema makes this less critical.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond those flags: results are limited to active pages, and password hashes/private URLs are deliberately omitted from the response.

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 a single sentence with no filler. Key qualifiers—active, public, owned by authenticated workspace, and excluded fields—are packed efficiently without repeating annotation 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?

This is a low-complexity, zero-parameter read operation with a full output schema and rich annotations. The description covers what is listed, whose pages are listed, and what sensitive data is excluded, so nothing essential is missing for an agent to 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 tool has zero parameters and the schema is empty with 100% coverage, so the description has no parameter documentation burden. The baseline for a zero-parameter tool is 4, and the description correctly focuses on output scope instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a precise action and resource: listing active public pages owned by the authenticated workspace, and explicitly excludes password hashes and private URLs. This scope distinguishes it from siblings like list_shared_with_me and search_workspace.

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 clear usage context: it is appropriate for retrieving the authenticated workspace's own active public pages. It does not explicitly name alternatives or state when not to use it, but the ownership and active-page scope make the intended use unambiguous.

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 annotations already declare the tool read-only, idempotent, and non-destructive, and the description does not contradict them. It adds useful context by saying the result is bounded metadata scoped to the authenticated user, but it does not disclose pagination behavior, ordering, or other limitations.

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 a single, front-loaded sentence with no filler. 'Bounded' is slightly vague and could obscure meaning, but overall the structure is appropriately concise.

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?

Annotations cover the safety profile and an output schema likely covers the return shape, which lowers the burden on the description. However, the concept of 'sellable content' and the relationship to the many sibling listing tools remain under-specified, so the description is minimally viable rather than fully 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 description coverage is 0%, so the description needed to compensate for the parameters, but it does not mention kind, limit, or cursor. The enum and constraints in the schema carry most of the meaning; 'bounded' only weakly hints at limit-based pagination.

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 uses a specific verb and resource: it lists metadata for the authenticated user's notes and media occurrences. It is clear enough to distinguish from many sibling tools by resource scope, though it does not explicitly name alternatives.

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 guidance on when to use this tool versus siblings like list_workspace, list_public_pages, or list_seller_sales. The term 'sellable' is not elaborated, and there are no exclusions or conditions.

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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those annotations: it returns only paid sales, applies bounds, and groups results by currency. This meaningfully clarifies what the operation does without contradicting 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 a single, front-loaded sentence with no filler. Every phrase earns its place: 'paid', 'bounded', and 'grouped by currency' all convey meaningful behavioral details.

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 output schema exists and the annotations already cover safety and idempotency, the description covers the essential semantics of the operation. The main gap is that cursor-based pagination behavior is not described, but the schema and output schema compensate for much of the missing 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 0%, and the description does not explain the limit or cursor parameters. The word 'bounded' hints at limit semantics but does not clarify the parameters, leaving the agent to infer usage solely from bare schema constraints.

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 ('return'), a specific resource ('seller sales'), and crucial scoping ('paid seller sales only'). It also adds distinguishing behavior ('bounded and grouped by currency'), which sets it apart from sibling list tools like list_sellable_content and list_public_pages.

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 'paid seller sales only' implies when the tool is appropriate, but it does not explicitly state when to prefer this tool over alternatives or mention exclusions such as unpaid sales. Usage context is present but left largely 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds a small behavioral detail by scoping results to items shared with the authenticated account, but it does not describe pagination, sorting, or response characteristics beyond what annotations and the output schema likely cover.

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 a single, front-loaded sentence with no wasted words. It states the action and scope efficiently.

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, read-only listing tool with strong annotations and an output schema, the description provides the essential contextual information: it lists shared collaboration targets and scopes them to the authenticated account. Nothing critical for invoking the tool 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?

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because there is no parametric ambiguity to resolve.

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 uses a specific verb ('List') and identifies a resource ('collaboration targets shared with the authenticated account'). It is clear enough about the general purpose, though the term 'collaboration targets' is somewhat vague and does not explicitly differentiate from nearby listing tools like list_collaboration_invitations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is provided, and the description does not mention alternatives or contrast with sibling tools. The reader must infer when this tool is appropriate based solely on the resource name.

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, and non-destructive behavior. The description adds useful behavioral scope: it returns the authenticated user's workspace contents and explicitly excludes private storage URLs, which is meaningful beyond the structured 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?

A single sentence that front-loads the core action and resource, states the inclusion scope, and adds a relevant exclusion without unnecessary detail. 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?

With zero parameters, strong annotations, and an output schema present, the description sufficiently covers what the tool does and what it returns. An agent can select and invoke this tool confidently from the provided 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?

The tool has zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The description still provides context about what the returned data represents, which is appropriate for a parameterless call.

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 uses a specific verb ('List') plus resource ('authenticated NotePom workspace tree, files and trash') and adds a meaningful qualifier ('without private storage URLs'). It clearly distinguishes this tool from sibling list tools such as list_public_pages and list_shared_with_me.

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 implies this is for retrieving the current user's workspace tree, files, and trash, but it does not explicitly state when to prefer it over alternatives or when not to use it. Usage context is present, but exclusions and sibling-tool routing are 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 convey readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds contextual value by specifying the operation is a move to either a folder or the workspace root, but it does not disclose potential conflict behavior, permission requirements, or effects on the file's previous location.

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 a single sentence with no filler, and the core action is front-loaded. However, it is so terse that it omits useful parameter or usage context, so it is concise but not fully appropriately sized for the tool's complexity.

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 four parameters, zero schema descriptions, and no usage differentiation from move_workspace_item, this description is not complete enough for an agent to invoke the tool confidently. The output schema reduces the need to describe return values, but parameter semantics, especially idempotencyKey, remain unexplained.

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 0%, so the description must compensate for undocumented parameters. It only loosely implies folderId's role via 'folder or workspace root' and does not explain idempotencyKey or expectedUpdatedAt, which are non-obvious and required or meaningful for correctness.

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 uses a specific verb ('Move') and resource ('an exact NotePom file') and identifies the destination ('into a folder or to the workspace root'). It does not explicitly differentiate from sibling tools like move_workspace_item, but the 'NotePom file' focus makes its primary purpose reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives such as move_workspace_item or trash_file. It does not mention prerequisites, when a move is appropriate, or what distinguishes this operation from similar sibling tools.

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

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

Annotations already declare mutating, non-destructive, and idempotent behavior, but the description adds little beyond the core action. It does not disclose effects like whether the source location is emptied, what happens to folder children, or whether destinationId null means root. There is no annotation contradiction, but the behavioral burden is mostly unmet.

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 a single, front-loaded sentence with no filler. It communicates the core operation and scope efficiently, earning its place without 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 mutating tool with five parameters and zero schema descriptions, this one-liner is under-specified. It omits critical context such as idempotency requirements, optimistic concurrency via expectedUpdatedAt, destination edge cases, and whether moving a folder cascades to children. Even with an output schema present, the operational guidance is incomplete.

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 0%, so the description must compensate, but it only mentions the entity types (note/folder) and the general notion of destination. It does not explain entityId, idempotencyKey, expectedUpdatedAt, or the nullable destinationId semantics, which would be essential for correct invocation.

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 ('Move') and resource ('a note or folder'), and adds the qualifier 'exact destination' to convey precision. This distinguishes it from siblings like move_file by scoping to workspace items (notes/folders) rather than generic files.

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 implies when to use the tool: when moving a note or folder to a precise destination. However, it provides no explicit exclusions or alternatives, such as when to use move_file or trash_workspace_item instead, leaving some routing 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is provided. The description adds useful context by explicitly ruling out Stripe session creation and purchase, but does not explain what 'preparing a handoff' actually involves or what side effects, if any, occur.

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 a single sentence with no redundant wording. It front-loads the main action ('Prepare') and immediately clarifies an important exclusion, making every word informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one required parameter and an output schema, so the basic calling context is fairly complete. However, the concept of a 'checkout handoff' is left undefined, and the description provides no workflow context about when this preparation step is needed or how it relates to Stripe session creation, leaving a notable gap for an agent deciding when to call 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 0%, and the description does not explain the meaning of the required 'slug' parameter beyond its name. Since the description mentions a public NotePom checkout handoff, it weakly implies the slug references a public page, but this is not explicit and the description does not compensate for the schema's lack of 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?

The description states a specific verb ('prepare') and a clear resource ('a public NotePom checkout handoff'), and explicitly distinguishes this from creating a Stripe session or purchase. It is clear what the tool does, though it does not name a competing sibling tool for direct comparison.

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 explicit guidance about when to use this tool versus alternatives such as create_stripe_onboarding_session. The statement 'without creating a Stripe session or purchase' clarifies a boundary but does not explain the intended workflow or conditions under which an agent should invoke this tool.

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 carry the safety profile (write op, non-destructive, idempotent, open-world), and the description adds context about the dual publish/update nature and the gating precondition of readiness and client confirmation. It does not, however, explain what an update does to existing listing data or what the readinessToken actually validates. No contradiction with 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 a single front-loaded sentence with no wasted words. However, for a tool with 10 parameters, 7 required, and a dual create/update mode, it is under-sized — this edges toward under-specification rather than disciplined conciseness.

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?

The tool has high complexity (10 params, idempotency semantics, readiness-token workflow, dual publish/update) with 0% schema description coverage, so the description must carry nearly all the explanatory weight. Thirteen words leave the agent guessing about ID relationships, preconditions, update behavior, and parameter provenance.

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 0%, so the description must compensate by explaining the 10 parameters, but it names none. Critical semantics are entirely undocumented: how to obtain readinessToken, the distinction between noteId, mediaId, and fileId, what amountMinor represents (minor currency units), and how idempotencyKey should be used.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Publish or update') and a specific resource ('media marketplace listing'), clearly conveying the action. The word 'media' partially distinguishes it from the sibling publish_note_listing, though it does not explicitly contrast against publish_note_listing or publish_page.

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 'after readiness and client confirmation' implies a workflow sequence — suggesting validate_listing_readiness should precede this call. However, there is no explicit statement of when to use this tool versus publish_note_listing or publish_page, and no exclusion or alternative conditions are 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 establish that this is a mutating (readOnlyHint=false), idempotent (idempotentHint=true), non-destructive write. The description adds genuine value beyond that: "publish or update" reveals upsert behavior, and "after readiness... confirmation" implies the tool enforces a readiness gate and may fail when a valid readinessToken is absent. No statement contradicts 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?

A single 14-word sentence that front-loads the verb and resource and appends the precondition at the end. There is zero filler; every word contributes either scope or sequencing 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?

Despite an output schema and annotations covering safety and return values, this tool has 8 parameters at 0% schema coverage, a near-twin sibling (publish_media_listing), and a prerequisite sibling (validate_listing_readiness). The description leaves critical gaps: how readinessToken is obtained, what distinguishes this from publish_media_listing, and the unit semantics of amountMinor. It is too thin for the 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?

Schema description coverage is 0%, so the description must compensate for the 8 parameters (5 required) but explains none of them. "After readiness" only loosely maps to readinessToken, and no meaning is added for amountMinor/currency units, idempotencyKey behavior, or the languageMode/contentLanguage distinction. The burden shift required at 0% coverage is unmet.

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?

"Publish or update" is a specific verb with clear upsert semantics, and "complete-note marketplace listing" names the resource precisely. The "complete-note" qualifier implicitly distinguishes this from the sibling publish_media_listing. However, it stops short of explicitly naming a contrasting sibling, so differentiation is partly left to inference.

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?

"After readiness and client confirmation" gives an explicit sequencing precondition, implying the agent should run validate_listing_readiness and obtain client sign-off before invoking. It does not name any alternative tools or state exclusions, such as when publish_media_listing or publish_page would be the correct choice.

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 annotations already communicate write semantics, idempotency, non-destructiveness, and open-world behavior, so the description need not re-state those. It adds only the outcome ('public page') and the exact entity scoping, but does not disclose whether an existing page is overwritten or what other side effects occur. This is acceptable given annotation coverage, but not richer than baseline.

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 a single, front-loaded sentence with no filler or repetition. It is compact, though arguably too sparse to compensate for the schema's missing parameter descriptions.

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?

Despite the output schema, an agent cannot infer key semantics such as what idempotencyKey does, how accessMode maps to password/public behavior, whether publishing is a create-or-update operation, or how this differs from publishing a listing. The description is too thin for a tool with this many parameters and tightly related siblings.

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 0% description coverage and seven parameters, so the description must carry the explanatory load. It only conveys entityType via 'note, folder or file'; required idempotencyKey, slug, accessMode, isIndexed, and isListedOnProfile are left entirely unexplained, which is a significant gap for a 7-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('publish') and resource scope ('exact note, folder or file'), and identifies the resulting artifact as a 'NotePom public page.' It does not explicitly contrast with closely related siblings like publish_note_listing or update_public_page, but the resource phrasing is specific enough to avoid gross confusion.

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 guidance on when to choose publish_page over sibling tools such as publish_note_listing, update_public_page, or unpublish_page. No prerequisites, exclusions, or lifecycle context are provided, so the agent must infer selection criteria solely from the tool name.

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 carry destructiveHint=true and idempotentHint=true, so the description's job is lighter. It adds valuable behavioral detail beyond the annotations by specifying that only unreferenced stored objects are deleted, and it does not contradict the annotation-provided 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?

A single, front-loaded sentence with no filler. It communicates the core operation and a key behavioral nuance without wasting 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?

The tool is simple and has annotations plus an output schema, so the description only needs to cover selection and invocation essentials. It covers purpose and destruction scope, but it leaves idempotencyKey semantics unexplained and does not explicitly distinguish itself from restore_trash_entry, which are meaningful gaps for an agent choosing and calling the 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 0%, so the description needed to compensate for both parameters. It indirectly clarifies trashEntryId as 'one exact trash entry,' but it says nothing about what idempotencyKey means, why it is required, or how it should be generated/used despite the idempotentHint annotation.

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 ('Permanently delete') and a specific resource ('one exact NotePom trash entry'), and adds a distinctive consequence ('and its unreferenced stored objects'). It clearly separates this from sibling operations like restore_trash_entry and trash_file.

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 it clear this is the permanent-destruction counterpart to trash/restore operations, giving an agent enough context to distinguish when to call it. However, it does not explicitly name alternatives or state 'use restore_trash_entry instead when recovery is desired,' so it stops short of a full when/when-not explanation.

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, and destructiveHint=false. The description adds valuable behavioral context beyond those: the 10 MiB size cap, base64 return encoding, authentication requirement, and the fact that no signed storage URL is needed. This is genuinely useful and does not contradict 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 a single sentence with no filler. It front-loads the action and then packs the key constraints—size limit, auth context, encoding, and URL behavior—into a compact, scannable structure.

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 operation with comprehensive annotations and an output schema, the description covers the essential behavioral details: size limit, encoding, authentication, and the no-signed-URL mechanism. Nothing needed to invoke the tool 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 0%, so the description must compensate for the fileId parameter, but it never mentions fileId or explains how to obtain or format it. The parameter name is self-evident to some degree, but the description adds no direct semantic guidance for the only required input.

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 uses a specific verb and resource: 'Read up to 10 MiB from an authenticated NotePom file as base64.' It clearly distinguishes this from sibling tools like get_note or upload_file by emphasizing file content, base64 encoding, and the absence of a signed storage URL.

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 implies when to use this tool—reading file content directly—but it does not explicitly name alternative tools or state when not to use it. The authenticated-file and no-signed-URL context provides some orientation, but an agent must mostly infer the choice from the tool name and sibling 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?

Beyond the annotations, the description discloses critical operational behavior: the call returns a one-time key, that key must be stored in the host secret store, and subsequent authorization must use it as a Bearer credential. This is valuable context for an agent handling credentials and side effects.

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 trigger condition, then the action and follow-up workflow. Every sentence provides necessary information 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?

The description covers the trigger, the account creation action, and the post-call credential workflow, and an output schema exists to document the return value. However, for a schema with zero parameter descriptions, the lack of any explanation of identifier/password/email leaves the agent to guess what values to supply.

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 0%, so the description needed to compensate, but it does not explain any parameter semantics. It does not clarify what identifier should be, how password relates to the account, or when email is needed. The parameter names are only weakly self-explanatory.

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 action ('create') and resource ('distinct NotePom agent account'), and gives a clear trigger condition. This distinguishes it from sibling verify_agent_account, which is about verification rather than 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 gives an explicit precondition: use this when persistent memory is requested and no credentials exist. It also explains the immediate next steps. However, it does not explicitly name alternative tools or state when not to use it, leaving some routing 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 idempotent, non-destructive, non-read-only behavior, so the description adds the semantic context that this is a targeted restore operation. It does not disclose edge-case behavior such as conflicts with the restored location, but that is beyond the annotation baseline.

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 with no filler; it names the action and the target without 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?

For a two-parameter tool with an output schema and safety annotations, this is minimally sufficient. However, it omits what restore entails (original location, conflict behavior) and any prerequisites, so it is not fully 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 description coverage is 0% and the description does not explain trashEntryId or idempotencyKey. 'Exact' weakly maps to trashEntryId, but the purpose of idempotencyKey is left entirely to the schema name and idempotentHint annotation, so the description fails to compensate for the low coverage.

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 uses a specific verb ('Restore') and resource ('NotePom trash entry'), and 'exact' conveys a targeted operation. This clearly distinguishes it from purge_trash_entry and the trash_* siblings.

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 intended use is implied by the name and verb: call this when a specific trash entry should be brought back. It does not explicitly contrast with purge_trash_entry for permanent deletion or state prerequisites like the entry still being in trash.

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 a scoping constraint beyond annotations (only invitations issued from the authenticated workspace). It does not contradict the destructiveHint and idempotentHint annotations, but it does not disclose consequences such as whether the invitee loses access immediately or whether revocation is permanent.

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 a single sentence that front-loads the verb and object, contains no filler, and every phrase ('exact', 'issued from the authenticated workspace') carries meaningful scoping information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with two required parameters and no output schema, the description is too thin. It does not explain what a successful revocation returns, what happens if the invitation was already accepted, or how idempotencyKey should be used. Annotations cover destructive/idempotent flags, but operational completeness remains a clear 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 0%, so the description must compensate. It provides minimal meaning for invitationId via 'exact invitation', but says nothing about idempotencyKey, its purpose, or why it is required. The parameter names are self-descriptive but not sufficient for correct invocation.

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 action ('Revoke') and resource ('collaboration invitation'), and adds a specific scoping detail: the invitation must be exact and issued from the authenticated workspace. This distinguishes it from siblings like invite_collaborator and revoke_collaborator, which target creating an invitation or revoking an existing collaborator.

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 context is implied by 'issued from the authenticated workspace' — the agent can infer it only applies to invitations this workspace sent. However, the description does not explicitly say when to prefer this over revoke_collaborator, nor does it address edge cases like already-accepted invitations.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the ownership boundary and exact-scope behavior, which is useful, but it does not explain consequences of revocation or idempotency behavior. Still, the annotation burden reduction makes this adequate.

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 a single front-loaded sentence with no filler. Every phrase earns its place by conveying scope, ownership, and exactness.

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 destructive tool, the annotations and schema carry much of the load. The description establishes what resource is acted on and the ownership constraint, but it does not explain where grantId comes from or what a successful revocation means behaviorally. Adequate but not rich.

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 0%, so the description must compensate. It maps 'one exact collaboration grant' to grantId conceptually, but it says nothing about idempotencyKey, why it is required, or how the two parameters relate. An agent gets no help understanding how to generate or use the idempotency key.

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 uses a specific verb ('Revoke'), a specific resource ('collaboration grant'), and adds meaningful qualifiers: 'one exact' and 'owned by the authenticated workspace'. This clearly distinguishes it from sibling tools like revoke_collaboration_invitation, which target invitations rather than existing grants.

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 wording implies use when the agent needs to revoke a specific, existing collaboration grant owned by the workspace, but it never explicitly says when not to use it or names alternatives. There is enough context to infer the general use case, but no explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds the scoped resource types, but doesn't clarify whether the search covers note content or only metadata, nor any pagination/result behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the action and scope with no filler. It earns its place, though the phrase 'authenticated workspace' is already implied by 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?

For a simple one-parameter, read-only, idempotent search tool, the description plus output schema and annotations cover the essential call context. It could be improved by stating whether note content is searched, but it isn't a critical 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?

With 0% schema description coverage, the description carries the burden, and it does indicate what the query targets (notes, folders, file metadata) but not query syntax, matching rules, or behavior at maxLength. For a single self-obvious query string, this is partial compensation.

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 'Search' and a concrete resource set: notes, folders, and file metadata, scoped to the authenticated workspace. This clearly differentiates from sibling read/list tools like list_workspace and get_note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use search_workspace versus list_workspace, list_shared_with_me, or get_note. The description doesn't mention any exclusions or alternatives, so an agent gets no routing help.

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 destructiveHint=true and idempotentHint=true, so the description only needs to add nuance. It adds that the file is moved to trash (not permanently purged) and targets an exact file, but it doesn't mention concurrency behavior via expectedUpdatedAt or what happens on missing files. No contradiction with 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 one clean sentence with no filler, and the action and object are front-loaded. 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?

The core action is clear, and annotations plus an output schema cover safety and return values. However, for a destructive operation requiring an idempotency key, the description leaves usage and parameter semantics under-specified, though the explicit schema property names partially compensate.

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 0%, so the description must compensate by explaining the parameters; it doesn't. fileId, idempotencyKey, and expectedUpdatedAt are never mentioned, leaving the roles of the idempotency key and optimistic-concurrency field entirely to inference.

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 ('Move'), resource ('an exact NotePom file'), and destination ('to trash'), so an agent can tell it is a targeted file-level trash operation. It doesn't explicitly contrast with siblings like trash_workspace_item or move_file, which prevents 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?

There is no guidance about when to choose this tool over trash_workspace_item, move_file, restore_trash_entry, or purge_trash_entry. The word 'exact' implies an identity-based file operation, but no conditions, exclusions, or alternative routing are 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 convey read-only=false, destructive=true, and idempotent=true. The description adds useful behavioral context beyond annotations by stating that descendants are included and that the destination is the NotePom trash, which clarifies the destructive scope.

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 a single, front-loaded sentence with no filler. Every word contributes to identifying the operation, scope, and destination, making it appropriately concise.

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 destructive tool with four parameters and no schema descriptions, the description is too thin. It omits the meaning of required idempotencyKey and optional expectedUpdatedAt, and it does not guide an agent on when to choose this over closely related sibling tools. Output schema and annotations help, but they do not fill these semantic 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?

The schema has 0% description coverage, so the description carries the burden for parameter meaning. It loosely maps 'note or folder' to entityType and 'exact' to entityId, but it does not explain idempotencyKey or expectedUpdatedAt, both of which are semantically important for correct invocation.

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 identifies the operation as moving a note or folder, including its descendants, to the NotePom trash. It is specific enough to distinguish this from most siblings like move_workspace_item and trash_file, though it does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus alternatives such as trash_file, move_workspace_item, purge_trash_entry, or restore_trash_entry. The description implies use when an exact note or folder should be trashed, but it provides no explicit selection criteria or exclusions.

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 annotations already indicate destructiveHint=true and readOnlyHint=false, and the description merely restates the mutation with 'Revoke' without adding behavioral context. It does not explain what happens to the page URL, the listing status, reversibility, or how the idempotency key factors into execution.

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 a single short sentence with no filler or repetition. The action and target are front-loaded, making the description efficient and easy to parse.

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 this is a destructive, idempotent mutation with a required idempotencyKey and open-world semantics, the description is too sparse. It omits side effects, prerequisites, and behavioral expectations, leaving the agent to infer critical invocation details.

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 0%, and the description does not compensate. It only vaguely refers to an 'exact' page, without explaining that pageId is the identifier or what idempotencyKey is for, its constraints, or why it is required.

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 clear action ('Revoke') and a specific resource ('NotePom public page'), making it evident that this tool unpublishes a page and is likely the inverse of publish_page. However, it does not explicitly differentiate itself from related siblings such as disable_listing or update_public_page.

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 guidance on when to use this tool versus alternatives. An agent is not told what conditions warrant unpublishing, how this differs from disable_listing, or when to choose update_public_page 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 flag idempotency and non-read-only behavior. The description adds useful behavioral context by specifying the exact note target, that the shared body is replaced, and that an optional expected revision is supported. This goes beyond the annotations, though it does not explain failure behavior or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. The key operation and distinguishing traits are stated immediately, and every phrase contributes meaning, despite minor grammatical ambiguity in 'from Markdown.'

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 five parameters and no output schema, the description is serviceable but not complete. It omits elaboration on the idempotency mechanism, the effect of a mismatched expected revision, and the workspace scope. The annotations help cover safety semantics, but an agent would still need to infer some call-critical details.

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 0%, so the description must compensate. It conceptually maps markdown, noteId, idempotencyKey, and expectedRevision, but it does not mention workspaceId or explain what expectedRevision actually controls. It adds some meaning beyond the raw schema but leaves gaps.

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 uses a specific verb ('Replace') and resource ('shared body of an exact collaboration note') and identifies the markdown input. It clearly distinguishes this from sibling tools focused on invitations, listing, or public pages, though it does not explicitly name a sibling or contrast itself with upsert_note/update_public_page.

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 no guidance on when to choose this tool over alternatives such as upsert_note or update_public_page. It mentions idempotency and expected revision, which hint at use cases, but there is no explicit context, exclusion, or alternative 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to restate those. However, it discloses little beyond the basic 'update settings' intent: it does not mention slug-change side effects, whether accessMode='password' changes require a password, how idempotencyKey behaves, or any consequential behavior such as URL changes. The description adds minimal behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence with no filler or repetition. It is structured well for readability, though the phrase 'an exact' is slightly awkward and the brevity sacrifices useful detail.

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 6-parameter update tool with 0% schema descriptions, the description is too sparse to be complete. Annotations and output schema cover some safety and result aspects, but the agent still lacks enough context about which settings can be updated together, what values are valid, and what happens when updating an exact public page. This is below the minimum viable level for a mutation tool with this parameter count.

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 0%, and the description does not compensate. 'Access and visibility settings' loosely maps to accessMode, isIndexed, and isListedOnProfile, but the description gives no meaning for slug, pageId, or idempotencyKey. An agent cannot determine parameter-specific semantics or constraints from the description alone.

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 ('Update'), a specific resource ('NotePom public page'), and the relevant aspect ('access and visibility settings'). It distinguishes the tool from siblings like publish_page and unpublish_page by focusing on updating settings rather than changing publication state, though it does not name those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives such as publish_page, unpublish_page, or disable_listing. Saying 'for an exact NotePom public page' implies the target is an existing page, but there is no clear statement of prerequisites, exclusions, or when another sibling should be preferred.

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 indicate this is a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations: the 10 MiB limit and the fact that the upload avoids exposing a private storage URL. It does not contradict 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 a single front-loaded sentence with no filler. Every phrase contributes meaning: the action, the size limit, the platform, and the privacy rationale. It is appropriately concise for a tool with structured annotations and 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 tool with 6 parameters, 0% schema description coverage, and no parameter-level guidance, the description is too sparse to support correct invocation. It does not explain idempotencyKey, folder placement, fileId reuse, or when to prefer this over sibling tools. The output schema reduces the need to describe return values, but the input side remains under-specified.

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 0%, and the description does not compensate by explaining any of the 6 parameters. While names like name, mimeType, and contentBase64 are somewhat self-explanatory, optional fileId/folderId and idempotencyKey semantics are left entirely undocumented, making correct invocation harder.

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 uses a specific verb and resource: 'Upload up to 10 MiB through NotePom'. It clearly states what the tool does and adds a meaningful constraint (size limit) plus a privacy motivation. The 'upload' action distinguishes it from read/trash/move siblings without confusion.

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 clear context about when to use this tool: uploading files up to 10 MiB through NotePom when avoiding exposure of a private storage URL matters. It does not explicitly name alternatives or exclusion conditions, but the context is specific enough to guide 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=false and idempotentHint=true, so the mutation and idempotency behavior is covered. The description adds that reparenting and renaming are possible, which is useful context. However, it does not disclose behavior around expectedUpdatedAt, conflicts, effects on child folders, or idempotency key handling beyond what the annotation already implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Every word contributes meaning and it is immediately clear what the tool does. This is appropriately concise.

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 5 parameters, zero schema descriptions, and an output schema, this one-liner is not enough for correct invocation. The agent is missing critical semantic context for idempotencyKey and expectedUpdatedAt, and the behavior of parentId (including null meaning) is not clarified. Annotations help with safety and idempotency, but the operational contract remains under-specified.

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 0%, so the description must compensate for explaining parameters, but it only names operations. Some meaning can be inferred: name maps to the folder name, folderId identifies the folder, parentId supports reparenting. However, the required idempotencyKey and expectedUpdatedAt are completely unexplained, leaving the agent without semantics for two important fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states specific operations on a specific resource: 'Create, rename or reparent a NotePom folder.' This clearly distinguishes it from sibling tools like upsert_note or move_workspace_item, and aligns with the title 'Create or update folder' while adding specificity.

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 does not say when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It only lists operations, leaving the agent to infer usage context from the tool name and title. No guidance is given about choosing upsert_folder over move_workspace_item or upsert_note.

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 annotations, the description adds valuable behavioral constraints: media never accepts bytes, URLs, or base64; omit folderId to create at workspace root. It does not contradict the idempotent or non-destructive hints.

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 compact, front-loaded with the core action, and every sentence carries useful guidance. It avoids fluff while covering content types, media workflow, and folder default behavior.

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 and many parameters, the description covers the main usage patterns but omits important upsert semantics such as how noteId selects create vs update, contentMode behavior, and the expectedUpdatedAt concurrency control. The output schema exists, so return values need no description.

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 low, and the description compensates for some key parameters such as media, markdown, pretextBlocks, and folderId. However, it does not explain critical parameters like noteId, contentMode, parentNoteId, expectedUpdatedAt, or idempotencyKey.

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 action and resource: 'Create or update a real Pretext note.' It clearly distinguishes from read-only and upload tools, though it does not explicitly contrast with siblings like update_collaboration_note or publish_page.

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 clear practical guidance: use markdown for simple content, pretextBlocks for visual content, and call upload_file before referencing media. It does not explicitly name alternatives for when not to use this tool, but the context is reasonably 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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior beyond annotations: the tool issues a short-lived, bound preparation token — a side effect that no annotation captures. The 'short-lived' and 'bound' qualifiers inform the agent about token lifecycle and coupling to specific inputs. It does not disclose failure behavior or what happens when validation fails, but the token disclosure is real added value with no contradiction to 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?

A single 17-word sentence that is front-loaded with verb and resource, with zero filler. Every element carries information: 'Purely' scopes the action, 'note or media listing' names the resource, 'short-lived bound preparation token' describes the outcome.

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?

An output schema exists and annotations are rich, which covers return values and safety. But critical gaps remain: the noteId/mediaId/fileId aliasing is unresolved, 'ready' is undefined, and the downstream consumption of the preparation token is unclear. For a 6-parameter tool with 0% schema coverage, the description needed to do substantially more work to make correct invocation possible.

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 0%, so the description carries the burden of explaining parameters — and it barely does. It hints that the kind enum maps to 'note or media listing,' but it never clarifies the relationship among fileId, noteId, and mediaId (three structurally identical $ref aliases), nor which ID to pass for which kind. amountMinor, currency, and what the token is 'bound' to are left unexplained. An agent cannot determine correct parameter selection from either the schema or the 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 names a specific verb ('validate'), a clear resource ('note or media listing'), and a concrete outcome ('issue a short-lived bound preparation token'). The 'Purely' prefix effectively signals this is not a publishing action, distinguishing it from siblings like publish_note_listing and publish_media_listing. However, it does not explicitly name any sibling it is not, and 'when ready' leaves the readiness condition vague.

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 implies a pre-publish validation context: an agent would call this to check readiness and obtain a preparation token before publishing, rather than to publish directly. But it never explicitly states when to use this tool versus publish_note_listing, publish_media_listing, or prepare_checkout, nor does it give any exclusions or alternatives. The guidance is implied, 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?

The description adds valuable behavioral context beyond the annotations: it discloses that the tool returns a one-time key, that the key must be stored in the host secret store, and that subsequent connections must use it as a Bearer credential. This explains side effects and authentication requirements without contradicting any 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?

The description is a single dense sentence with no filler. It front-loads the core purpose and then provides the essential post-condition and credential-handling steps. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter verification tool with an output schema and supporting annotations, the description covers the main flow well: what the tool completes, what to do with the result, and how to use it later. The only notable gap is the lack of explicit parameter semantics, but this does not make the tool uncallable.

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 0%, and the description does not explicitly map the two required parameters. It never states that requestId is the registration request identifier or that code is the emailed six-digit verification code; the agent must infer this from parameter names, the pattern, and the phrase 'email-required'.

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 action ('Complete an email-required agent registration') and clearly identifies the resource and flow being finished. It also distinguishes the tool from the sibling register_agent_account by framing this as the completion step rather than the initial registration step.

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 clear context: this is the follow-up step after an email-required agent registration, where the agent has a requestId and a code. It does not explicitly name alternatives or state when not to use it, but the context strongly implies the correct placement in the registration flow.

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